graders/documentation.py

"""
graders/documentation.py — Documentation quality grader.
Weight: 5% of total reward.

Checks:
  - Functions have docstrings
  - Type hints on parameters and return values
  - No bare except clauses
"""
import ast
from typing import Dict, Any


def grade_documentation(code: str) -> Dict[str, Any]:
    try:
        tree = ast.parse(code)
    except SyntaxError:
        return {"score": 0.0, "feedback": "SyntaxError — cannot check documentation."}

    functions = [n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)]
    if not functions:
        return {"score": 0.8, "feedback": "No functions found — partial credit."}

    has_docstring = sum(1 for f in functions if ast.get_docstring(f))
    has_type_hints = sum(
        1 for f in functions
        if f.returns or any(a.annotation for a in f.args.args)
    )

    doc_score = has_docstring / len(functions)
    hint_score = has_type_hints / len(functions)
    final = round(doc_score * 0.5 + hint_score * 0.5, 4)

    return {
        "score": final,
        "feedback": (
            f"{has_docstring}/{len(functions)} functions have docstrings, "
            f"{has_type_hints}/{len(functions)} have type hints."
        ),
    }