errgrade 0.1.0__tar.gz

errgrade-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mgkvibez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

errgrade-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: errgrade
+Version: 0.1.0
+Summary: Grade the error messages your code raises: what broke, where, and what to do next.
+Author: mgkvibez
+License: MIT
+Keywords: linter,errors,dx,code-review,developer-tools,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# errgrade
+
+Grade the error messages your code raises: does it say **what** broke, **where**, and **what to do next**.
+
+```
+$ errgrade examples/before.py
+errgrade: 4 finding(s) across 6 message(s) in 1 file(s), worst high
+1 of 6 graded message(s) fall below C
+
+[HIGH] examples/before.py:6 (vague-error)
+  message: 'failed'
+  why:     the message does not say what went wrong
+  missing: what, where, next
+  grade:   D (0/100)
+
+[HIGH] examples/before.py:8 (literal-placeholder)
+  message: 'missing {path}'
+  why:     braces are shown to the reader verbatim: this string is never formatted
+  missing: next
+  grade:   B (75/100)
+
+[LOW] examples/before.py:10 (no-next-step)
+  message: 'config file is empty'
+  why:     nothing tells the reader what to do next
+  missing: next
+  grade:   B (75/100)
+```
+
+Note what it does **not** flag: `amount must be positive, got {amount}` and
+`currency must be one of NGN, USD` pass, because they answer all three questions.
+
+## Install
+
+```bash
+pipx install errgrade
+```
+
+Python 3.9+, **zero runtime dependencies**. The analysis is a standard-library AST pass.
+
+## Usage
+
+```bash
+# grade the current directory (tests excluded: their messages are not user-facing)
+errgrade
+
+# one file or directory, and see the worst offenders first
+errgrade src --top 5
+
+# machine-readable, for a bot or a CI annotation step
+errgrade --json
+
+# fail CI only on the messages a user would actually see going wrong
+errgrade src --fail-on high
+```
+
+Exit codes: `0` nothing at or above the threshold, `1` findings at or above it,
+`2` usage error. A linter that exits 1 for its own mistakes makes CI lie, which is why
+those are separate.
+
+`--fail-on` defaults to `medium`. `low` findings never fail a run unless you ask.
+
+## Why it exists
+
+Error messages are the only part of your code that runs at the worst moment of someone's
+day. They are also the one thing nobody reviews: a pull request diff shows a new
+`raise`, and reviewers look at the condition, not the sentence.
+
+The cost is invisible and real. `ValueError("failed")` reaches a user as a dead end, and
+reaches you as a support ticket that says "it doesn't work". The difference between that
+and `amount must be positive, got -5` is four words and one value.
+
+## How the grading works
+
+Every message is scored on three axes, because those are the three questions a stuck
+person asks:
+
+| Axis | Weight | Satisfied by |
+|---|---|---|
+| what | 40 | not a known filler phrase, and at least two words |
+| where | 35 | an interpolated value, a named subject ("tenant is archived"), a location noun, or a list of valid values |
+| next | 25 | an imperative ("set", "pass", "check", "give"), a constraint ("must be", "expected"), or the allowed values |
+
+100 becomes `A`, 85+ `A`, 70+ `B`, 50+ `C`, below that `D`. A message with no
+interpolated value and no named subject cannot tell one failure from another, which is
+what pushes it below `C`.
+
+The values come from the syntax tree, not the text: an f-string, `.format()` or `%`
+counts as interpolation because a value genuinely flows in. `"{name}"` written as a plain
+string counts as a bug, because the reader sees the braces.
+
+## Rules
+
+| Severity | Rule | What it means |
+|---|---|---|
+| high | `vague-error` | the message does not say what went wrong (`"failed"`, `"invalid input"`) |
+| high | `literal-placeholder` | braces reach the reader verbatim because the string is never formatted |
+| medium | `no-context` | no value and no subject: the reader cannot tell which case this is |
+| medium | `bare-exception` | `raise ValueError()` with no message at all |
+| low | `no-next-step` | nothing tells the reader what to do next |
+
+One primary finding per message: a vague message is not also reported for context and
+next steps, because stacking three findings on one word is noise, not help.
+
+## Suppressing a message
+
+Some messages are deliberately terse. Say so on the line:
+
+```python
+raise ValueError("failed")  # errgrade: ignore
+```
+
+Only that line is suppressed. There is no config file to fall out of sync.
+
+## What this deliberately does not do
+
+- **Python only, for now.** The grading itself takes a string and does not care where it
+  came from; only the AST extraction is Python-specific.
+- **It grades literal messages.** `raise ValueError(msg)` is skipped, because grading a
+  variable would mean inventing its contents.
+- **It is a heuristic, not a review.** A high grade means the message answers the three
+  questions as far as a static tool can tell, not that it is good writing. "No issues
+  found" means no known weak pattern matched, and is not a guarantee.
+- **It does not touch logging.** Log lines are for people with the code open; `raise`
+  strings are what users and callers read.
+- **It does not rewrite your messages.** It tells you which ones are a dead end and why.
+
+## Tests
+
+```bash
+python -m pytest -q      # 52 tests
+bash scripts/verify.sh   # the release gate, 6 checks
+```
+
+Contributions: the rules live in `errgrade/analyze.py`, the scoring in
+`errgrade/grade.py`, and every rule has a test in `tests/test_analyze.py`. A new
+heuristic needs a case it must flag and a case it must not.
+
+## License
+
+MIT.

errgrade-0.1.0/README.md

@@ -0,0 +1,140 @@
+# errgrade
+
+Grade the error messages your code raises: does it say **what** broke, **where**, and **what to do next**.
+
+```
+$ errgrade examples/before.py
+errgrade: 4 finding(s) across 6 message(s) in 1 file(s), worst high
+1 of 6 graded message(s) fall below C
+
+[HIGH] examples/before.py:6 (vague-error)
+  message: 'failed'
+  why:     the message does not say what went wrong
+  missing: what, where, next
+  grade:   D (0/100)
+
+[HIGH] examples/before.py:8 (literal-placeholder)
+  message: 'missing {path}'
+  why:     braces are shown to the reader verbatim: this string is never formatted
+  missing: next
+  grade:   B (75/100)
+
+[LOW] examples/before.py:10 (no-next-step)
+  message: 'config file is empty'
+  why:     nothing tells the reader what to do next
+  missing: next
+  grade:   B (75/100)
+```
+
+Note what it does **not** flag: `amount must be positive, got {amount}` and
+`currency must be one of NGN, USD` pass, because they answer all three questions.
+
+## Install
+
+```bash
+pipx install errgrade
+```
+
+Python 3.9+, **zero runtime dependencies**. The analysis is a standard-library AST pass.
+
+## Usage
+
+```bash
+# grade the current directory (tests excluded: their messages are not user-facing)
+errgrade
+
+# one file or directory, and see the worst offenders first
+errgrade src --top 5
+
+# machine-readable, for a bot or a CI annotation step
+errgrade --json
+
+# fail CI only on the messages a user would actually see going wrong
+errgrade src --fail-on high
+```
+
+Exit codes: `0` nothing at or above the threshold, `1` findings at or above it,
+`2` usage error. A linter that exits 1 for its own mistakes makes CI lie, which is why
+those are separate.
+
+`--fail-on` defaults to `medium`. `low` findings never fail a run unless you ask.
+
+## Why it exists
+
+Error messages are the only part of your code that runs at the worst moment of someone's
+day. They are also the one thing nobody reviews: a pull request diff shows a new
+`raise`, and reviewers look at the condition, not the sentence.
+
+The cost is invisible and real. `ValueError("failed")` reaches a user as a dead end, and
+reaches you as a support ticket that says "it doesn't work". The difference between that
+and `amount must be positive, got -5` is four words and one value.
+
+## How the grading works
+
+Every message is scored on three axes, because those are the three questions a stuck
+person asks:
+
+| Axis | Weight | Satisfied by |
+|---|---|---|
+| what | 40 | not a known filler phrase, and at least two words |
+| where | 35 | an interpolated value, a named subject ("tenant is archived"), a location noun, or a list of valid values |
+| next | 25 | an imperative ("set", "pass", "check", "give"), a constraint ("must be", "expected"), or the allowed values |
+
+100 becomes `A`, 85+ `A`, 70+ `B`, 50+ `C`, below that `D`. A message with no
+interpolated value and no named subject cannot tell one failure from another, which is
+what pushes it below `C`.
+
+The values come from the syntax tree, not the text: an f-string, `.format()` or `%`
+counts as interpolation because a value genuinely flows in. `"{name}"` written as a plain
+string counts as a bug, because the reader sees the braces.
+
+## Rules
+
+| Severity | Rule | What it means |
+|---|---|---|
+| high | `vague-error` | the message does not say what went wrong (`"failed"`, `"invalid input"`) |
+| high | `literal-placeholder` | braces reach the reader verbatim because the string is never formatted |
+| medium | `no-context` | no value and no subject: the reader cannot tell which case this is |
+| medium | `bare-exception` | `raise ValueError()` with no message at all |
+| low | `no-next-step` | nothing tells the reader what to do next |
+
+One primary finding per message: a vague message is not also reported for context and
+next steps, because stacking three findings on one word is noise, not help.
+
+## Suppressing a message
+
+Some messages are deliberately terse. Say so on the line:
+
+```python
+raise ValueError("failed")  # errgrade: ignore
+```
+
+Only that line is suppressed. There is no config file to fall out of sync.
+
+## What this deliberately does not do
+
+- **Python only, for now.** The grading itself takes a string and does not care where it
+  came from; only the AST extraction is Python-specific.
+- **It grades literal messages.** `raise ValueError(msg)` is skipped, because grading a
+  variable would mean inventing its contents.
+- **It is a heuristic, not a review.** A high grade means the message answers the three
+  questions as far as a static tool can tell, not that it is good writing. "No issues
+  found" means no known weak pattern matched, and is not a guarantee.
+- **It does not touch logging.** Log lines are for people with the code open; `raise`
+  strings are what users and callers read.
+- **It does not rewrite your messages.** It tells you which ones are a dead end and why.
+
+## Tests
+
+```bash
+python -m pytest -q      # 52 tests
+bash scripts/verify.sh   # the release gate, 6 checks
+```
+
+Contributions: the rules live in `errgrade/analyze.py`, the scoring in
+`errgrade/grade.py`, and every rule has a test in `tests/test_analyze.py`. A new
+heuristic needs a case it must flag and a case it must not.
+
+## License
+
+MIT.

errgrade-0.1.0/errgrade/__init__.py

@@ -0,0 +1,3 @@
+"""errgrade: grade the error messages your code raises."""
+
+__version__ = "0.1.0"

errgrade-0.1.0/errgrade/analyze.py

@@ -0,0 +1,269 @@
+"""Find the messages a Python program would actually show a person.
+
+Only ``raise`` sites count. A string handed to ``logging.error`` is for operators who
+have the code open; a string in ``raise`` is what a user or a caller reads when
+something is already going wrong, and that is the one worth grading.
+
+Extraction is AST-based on purpose. Grepping for ``raise`` finds it inside comments,
+docstrings and string literals, which is how most "quick linter" scripts end up with
+noise instead of findings.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Sequence, Tuple
+
+from .grade import PLACEHOLDER_RE, Grade, grade_message
+
+SEVERITY_ORDER = {"high": 0, "medium": 1, "low": 2}
+
+#: Frameworks put the human-facing text in a keyword, not a positional argument:
+#: ``HTTPException(status_code=401, detail="invalid signature")``.
+MESSAGE_KWARGS = ("detail", "message", "msg", "reason")
+
+#: Inline suppression, so a deliberate message does not need a config file.
+PRAGMA = "errgrade: ignore"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One suspicious message, located well enough to fix without searching."""
+
+    path: str
+    line: int
+    rule: str
+    severity: str
+    message: str
+    detail: str
+    grade: Grade
+
+    def to_dict(self) -> dict:
+        return {
+            "path": self.path,
+            "line": self.line,
+            "rule": self.rule,
+            "severity": self.severity,
+            "message": self.message,
+            "detail": self.detail,
+            **self.grade.to_dict(),
+        }
+
+
+@dataclass
+class Report:
+    findings: List[Finding] = field(default_factory=list)
+    graded: int = 0
+    files: int = 0
+    below_c: int = 0
+
+    def sorted_findings(self) -> List[Finding]:
+        return sorted(self.findings, key=lambda f: (SEVERITY_ORDER[f.severity], f.path, f.line))
+
+
+def _call_name(node: ast.AST) -> str:
+    if isinstance(node, ast.Call):
+        func = node.func
+        if isinstance(func, ast.Name):
+            return func.id
+        if isinstance(func, ast.Attribute):
+            return func.attr
+    if isinstance(node, ast.Name):
+        return node.id
+    return ""
+
+
+def _string_parts(node: ast.AST) -> Optional[Tuple[str, bool]]:
+    """Return (text, interpolated) for a message expression, or None if unreadable.
+
+    ``interpolated`` marks a value flowing into the text. That is the only honest
+    signal that a message says *where* the failure happened.
+    """
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value, False
+    if isinstance(node, ast.JoinedStr):
+        text = "".join(
+            part.value if isinstance(part, ast.Constant) and isinstance(part.value, str) else "<value>"
+            for part in node.values
+        )
+        has_value = any(isinstance(part, ast.FormattedValue) for part in node.values)
+        return text, has_value
+    if isinstance(node, ast.BinOp):
+        # "x" % name  or  "x" + name
+        if isinstance(node.op, (ast.Mod, ast.Add)):
+            left = _string_parts(node.left)
+            if left:
+                text, _ = left
+                return text, True
+            right = _string_parts(node.right)
+            if right and isinstance(node.op, ast.Add):
+                text, _ = right
+                return text, True
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+        # "x {}".format(name)  /  f-string style helpers
+        if node.func.attr == "format":
+            base = _string_parts(node.func.value)
+            if base:
+                text, _ = base
+                # "{}".format(x) interpolates; "{a}" without args does not.
+                return text, bool(node.args or node.keywords)
+    return None
+
+
+def _message_node(exc: ast.AST) -> Optional[ast.AST]:
+    """The expression holding the message, wherever this framework keeps it."""
+    if not isinstance(exc, ast.Call):
+        return None
+    if exc.args:
+        return exc.args[0]
+    for kw in exc.keywords:
+        if kw.arg in MESSAGE_KWARGS:
+            return kw.value
+    return None
+
+
+def _docstring_lines(tree: ast.AST) -> set:
+    """Lines occupied by docstrings, so a message quoted in prose is not graded."""
+    lines = set()
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            body = getattr(node, "body", None)
+            if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant) \
+                    and isinstance(body[0].value.value, str):
+                first, last = body[0].lineno, getattr(body[0], "end_lineno", body[0].lineno)
+                lines.update(range(first, last + 1))
+    return lines
+
+
+def analyze_source(source: str, path: str = "<src>") -> List[Finding]:
+    """Every finding in one file."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    ignored = {i + 1 for i, line in enumerate(source.splitlines()) if PRAGMA in line}
+    doc_lines = _docstring_lines(tree)
+    findings: List[Finding] = []
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Raise) or node.exc is None:
+            continue
+        exc = node.exc
+        name = _call_name(exc)
+        if not name:
+            continue
+        line = node.lineno
+        if line in ignored:
+            continue
+
+        node_for_message = _message_node(exc)
+        if node_for_message is None:
+            # A raise with framing keywords but no readable text (e.g. status_code=500)
+            # cannot be graded honestly, so it is skipped rather than guessed at.
+            if isinstance(exc, ast.Call) and (exc.args or exc.keywords):
+                continue
+            findings.append(Finding(
+                path, line, "bare-exception", "medium", name + "()",
+                "raised with no message, so the caller learns nothing beyond the type",
+                grade_message(""),
+            ))
+            continue
+
+        parts = _string_parts(node_for_message)
+        if parts is None:
+            continue
+        text, interpolated = parts
+
+        if not text.strip():
+            continue
+        grade = grade_message(text, interpolated=interpolated)
+
+        # A brace placeholder in a string that is not interpolated reaches the user
+        # literally, which is a bug rather than a style problem.
+        if not interpolated and PLACEHOLDER_RE.search(text):
+            findings.append(Finding(
+                path, line, "literal-placeholder", "high", text,
+                "braces are shown to the reader verbatim: this string is never formatted",
+                grade,
+            ))
+            continue
+
+        if not grade.what:
+            findings.append(Finding(
+                path, line, "vague-error", "high", text,
+                "the message does not say what went wrong",
+                grade,
+            ))
+            continue  # one primary verdict per message; the low rules below add noise
+        elif not grade.where:
+            findings.append(Finding(
+                path, line, "no-context", "medium", text,
+                "no value or location: the reader cannot tell which case this is",
+                grade,
+            ))
+            continue
+
+        if not grade.next:
+            findings.append(Finding(
+                path, line, "no-next-step", "low", text,
+                "nothing tells the reader what to do next",
+                grade,
+            ))
+
+    return findings
+
+
+def analyze_files(files: Sequence[Path], *, include_tests: bool = False) -> Report:
+    """Analyse a list of paths, expanding directories."""
+    report = Report()
+    paths: List[Path] = []
+    for p in files:
+        if p.is_dir():
+            paths.extend(sorted(p.rglob("*.py")))
+        elif p.suffix == ".py":
+            paths.append(p)
+
+    for path in paths:
+        if _looks_like_artifact(path):
+            continue
+        if not include_tests and _looks_like_test(path):
+            continue
+        try:
+            source = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        report.files += 1
+        file_findings = analyze_source(source, str(path))
+        report.findings.extend(file_findings)
+        report.graded += _count_raises(source)
+        report.below_c += sum(1 for f in file_findings if f.grade.letter in ("C", "D"))
+    return report
+
+
+SKIP_DIRS = frozenset({"build", "dist", "node_modules", ".git", ".venv", "venv",
+                       "site-packages", "__pycache__", ".tox", ".mypy_cache",
+                       "egg-info", ".eggs"})
+
+
+def _looks_like_artifact(path: Path) -> bool:
+    """Build outputs and vendored trees are not your code to fix."""
+    return any(p.lower() in SKIP_DIRS or p.lower().endswith(".egg-info") for p in path.parts)
+
+
+def _looks_like_test(path: Path) -> bool:
+    parts = [p.lower() for p in path.parts]
+    if "tests" in parts or "test" in parts:
+        return True
+    name = path.name.lower()
+    return name.startswith("test_") or name.endswith("_test.py") or name == "conftest.py"
+
+
+def _count_raises(source: str) -> int:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return 0
+    return sum(1 for node in ast.walk(tree) if isinstance(node, ast.Raise) and node.exc is not None)