tesserakit-docs 0.4.0__py3-none-any.whl

tessera_docs/__init__.py

@@ -0,0 +1,3 @@
+"""Tessera docs pack."""
+
+__version__ = "0.3.1"

tessera_docs/cli.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from tessera_core.models import RunContext
+
+from tessera_docs.pack import DocsPack
+
+console = Console()
+docs_app = typer.Typer(help="Measure Python docstring coverage for public symbols.")
+
+
+@docs_app.command("coverage")
+def coverage_cmd(
+    input: Path = typer.Option(Path("."), "--input", "-i", exists=True, readable=True, help="Project directory."),
+    output: Path = typer.Option(Path("docs_pack"), "--output", "-o", help="Output directory."),
+    include_tests: bool = typer.Option(False, "--include-tests", help="Include test files in the scan."),
+) -> None:
+    """Scan Python source and report docstring coverage for public symbols."""
+    ctx = RunContext(job_name="docs", output_dir=output)
+    pack = DocsPack()
+    artifacts = pack.run(input_path=input, ctx=ctx, options={"include_tests": include_tests})
+
+    table = Table(title="Docs Pack Created")
+    table.add_column("Artifact")
+    table.add_column("Path")
+    table.add_column("Kind")
+    for art in artifacts:
+        table.add_row(art.name, str(art.path), art.kind)
+    console.print(table)
+
+    summary = Table(title="Run Summary")
+    summary.add_column("Metric")
+    summary.add_column("Value")
+    summary.add_row("run_id", ctx.run_id)
+    summary.add_row("symbols", str(ctx.metadata.get("record_count", 0)))
+    summary.add_row("findings", str(ctx.metadata.get("finding_count", 0)))
+    console.print(summary)
+
+
+def register(root_app: typer.Typer) -> None:
+    root_app.add_typer(docs_app, name="docs")

tessera_docs/compiler.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+from tessera_core.artifacts import write_jsonl, write_markdown
+from tessera_core.models import Artifact, RunContext, ValidationFinding
+
+from tessera_docs.loader import load_docs_records
+from tessera_docs.schema import DocSymbol
+from tessera_docs.validator import validate_docs_records
+
+
+def load_records(input_path: Path, options: dict[str, Any]) -> list[DocSymbol]:
+    return load_docs_records(input_path, options)
+
+
+def validate_records(symbols: list[DocSymbol], options: dict[str, Any]) -> list[ValidationFinding]:
+    return validate_docs_records(symbols, options)
+
+
+def write_artifacts(symbols: list[DocSymbol], ctx: RunContext, options: dict[str, Any]) -> list[Artifact]:
+    ctx.output_dir.mkdir(parents=True, exist_ok=True)
+    findings: list[ValidationFinding] = ctx.metadata.get("findings") or validate_records(symbols, options)
+
+    symbols_jsonl = ctx.output_dir / "symbols.jsonl"
+    index_md = ctx.output_dir / "index.md"
+    validation_md = ctx.output_dir / "validation_report.md"
+    coverage_md = ctx.output_dir / "coverage_report.md"
+    undocumented_md = ctx.output_dir / "undocumented.md"
+
+    write_jsonl(symbols_jsonl, [s.model_dump() for s in symbols])
+    write_markdown(index_md, _render_index(symbols, options))
+    write_markdown(validation_md, _render_validation(symbols, findings))
+    write_markdown(coverage_md, _render_coverage(symbols))
+    write_markdown(undocumented_md, _render_undocumented(symbols))
+
+    return [
+        Artifact(name="symbols.jsonl", path=symbols_jsonl, kind="jsonl"),
+        Artifact(name="index.md", path=index_md, kind="markdown"),
+        Artifact(name="validation_report.md", path=validation_md, kind="markdown"),
+        Artifact(name="coverage_report.md", path=coverage_md, kind="markdown"),
+        Artifact(name="undocumented.md", path=undocumented_md, kind="markdown"),
+    ]
+
+
+def _coverage(symbols: list[DocSymbol]) -> tuple[int, int, float]:
+    public = [s for s in symbols if s.is_public]
+    documented = sum(1 for s in public if s.has_docstring)
+    pct = (documented / len(public)) if public else 1.0
+    return documented, len(public), pct
+
+
+def _render_index(symbols: list[DocSymbol], options: dict[str, Any]) -> str:
+    documented, total, pct = _coverage(symbols)
+    lines = ["# Documentation Coverage", ""]
+    lines.append(f"- Files scanned: {options.get('_file_count', 0)}")
+    lines.append(f"- Public symbols: {total}")
+    lines.append(f"- Documented: {documented}")
+    lines.append(f"- Coverage: {pct*100:.0f}%")
+    return "\n".join(lines) + "\n"
+
+
+def _render_validation(symbols: list[DocSymbol], findings: list[ValidationFinding]) -> str:
+    lines = ["# Validation Report", ""]
+    lines.append(f"- Symbols: {len(symbols)}")
+    lines.append(f"- Findings: {len(findings)}")
+    lines.append("")
+    by_sev = Counter(f.severity for f in findings)
+    lines.append("## Severity Breakdown")
+    lines.append("")
+    for sev in ("error", "warning", "info"):
+        lines.append(f"- {sev}: {by_sev.get(sev, 0)}")
+    lines.append("")
+    if findings:
+        lines.append("## Findings")
+        lines.append("")
+        for f in findings[:300]:
+            lines.append(f"- **{f.severity.upper()}** `{f.code}`: {f.message}")
+        if len(findings) > 300:
+            lines.append(f"- ... {len(findings) - 300} more findings omitted")
+    return "\n".join(lines)
+
+
+def _render_coverage(symbols: list[DocSymbol]) -> str:
+    lines = ["# Coverage Report", ""]
+    documented, total, pct = _coverage(symbols)
+    lines.append(f"- Public symbols: {total}")
+    lines.append(f"- Documented: {documented} ({pct*100:.0f}%)")
+    lines.append("")
+
+    # by kind
+    lines.append("## By kind")
+    lines.append("")
+    lines.append("| Kind | Public | Documented | Coverage |")
+    lines.append("|---|---:|---:|---:|")
+    by_kind: dict[str, list[DocSymbol]] = defaultdict(list)
+    for s in symbols:
+        if s.is_public:
+            by_kind[s.kind].append(s)
+    for kind in ("module", "class", "function", "method"):
+        items = by_kind.get(kind, [])
+        if not items:
+            continue
+        doc = sum(1 for s in items if s.has_docstring)
+        lines.append(f"| {kind} | {len(items)} | {doc} | {100*doc/len(items):.0f}% |")
+    lines.append("")
+
+    # worst files
+    by_file: dict[str, list[DocSymbol]] = defaultdict(list)
+    for s in symbols:
+        if s.is_public:
+            by_file[s.path].append(s)
+    rows = []
+    for path, items in by_file.items():
+        doc = sum(1 for s in items if s.has_docstring)
+        rows.append((doc / len(items), path, doc, len(items)))
+    rows.sort()
+    lines.append("## Lowest-coverage files")
+    lines.append("")
+    lines.append("| File | Documented | Public | Coverage |")
+    lines.append("|---|---:|---:|---:|")
+    for cov, path, doc, tot in rows[:15]:
+        lines.append(f"| `{path}` | {doc} | {tot} | {cov*100:.0f}% |")
+    return "\n".join(lines) + "\n"
+
+
+def _render_undocumented(symbols: list[DocSymbol]) -> str:
+    missing = [s for s in symbols if s.is_public and not s.has_docstring]
+    lines = ["# Undocumented Public Symbols", ""]
+    lines.append(f"- Count: {len(missing)}")
+    lines.append("")
+    if not missing:
+        lines.append("_Everything public is documented._")
+        return "\n".join(lines) + "\n"
+    lines.append("| File | Symbol | Kind | Line |")
+    lines.append("|---|---|---|---:|")
+    for s in sorted(missing, key=lambda x: (x.path, x.lineno)):
+        lines.append(f"| `{s.path}` | `{s.qualname or s.name}` | {s.kind} | {s.lineno} |")
+    return "\n".join(lines) + "\n"

tessera_docs/loader.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from tessera_docs.scan import discover_py_files, extract_symbols
+from tessera_docs.schema import DocSymbol
+
+
+def load_docs_records(input_path: Path, options: dict[str, Any]) -> list[DocSymbol]:
+    """Extract documentable symbols from every (non-test) Python file."""
+    root = input_path if input_path.is_dir() else input_path.parent
+    include_tests = bool(options.get("include_tests", False))
+
+    symbols: list[DocSymbol] = []
+    parse_errors: list[str] = []
+    files = discover_py_files(root, include_tests=include_tests)
+    for f in files:
+        syms, err = extract_symbols(root, f)
+        symbols.extend(syms)
+        if err:
+            parse_errors.append(err)
+
+    options["_parse_errors"] = parse_errors
+    options["_file_count"] = len(files)
+    options["_root"] = str(root)
+    return symbols

tessera_docs/pack.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from tessera_core.jobpack import JobPack
+from tessera_core.models import Artifact, RunContext, ValidationFinding
+
+from tessera_docs.compiler import load_records, validate_records, write_artifacts
+
+
+class DocsPack(JobPack):
+    name = "docs"
+    version = "0.3.1"
+
+    def normalize(self, input_path: Path, options: dict[str, Any]) -> list[Any]:
+        return load_records(input_path, options)
+
+    def validate(
+        self,
+        records: list[Any],
+        options: dict[str, Any],
+    ) -> list[ValidationFinding]:
+        return validate_records(records, options)
+
+    def generate(
+        self,
+        records: list[Any],
+        ctx: RunContext,
+        options: dict[str, Any],
+    ) -> list[Artifact]:
+        return write_artifacts(records, ctx, options)
+
+
+def create_pack() -> DocsPack:
+    return DocsPack()

tessera_docs/scan.py

@@ -0,0 +1,83 @@
+"""Extract documentable symbols from Python source via the ast module.
+
+Source is parsed, never imported or executed.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from tessera_docs.schema import DocSymbol
+
+IGNORE_DIRS = {
+    ".git", ".venv", "venv", "node_modules", "__pycache__", ".pytest_cache",
+    "dist", "build", ".tox", "target", ".mypy_cache", ".ruff_cache",
+}
+
+
+def is_public(name: str) -> bool:
+    return not name.startswith("_")
+
+
+def _is_test_path(rel: Path) -> bool:
+    parts = [p.lower() for p in rel.parts]
+    if any(p in ("test", "tests", "__tests__") for p in parts[:-1]):
+        return True
+    n = rel.name.lower()
+    return n.startswith("test_") or n.endswith("_test.py")
+
+
+def discover_py_files(root: Path, include_tests: bool = False) -> list[Path]:
+    out: list[Path] = []
+    for p in sorted(root.rglob("*.py")):
+        rel = p.relative_to(root)
+        if any(part in IGNORE_DIRS for part in rel.parts):
+            continue
+        if not include_tests and _is_test_path(rel):
+            continue
+        out.append(p)
+    return out
+
+
+def extract_symbols(root: Path, path: Path) -> tuple[list[DocSymbol], str | None]:
+    """Return (symbols, parse_error). Parse error is a string or None."""
+    rel = path.relative_to(root).as_posix()
+    try:
+        source = path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+    except (OSError, UnicodeDecodeError, SyntaxError) as exc:
+        return [], f"{rel}: {exc}"
+
+    symbols: list[DocSymbol] = []
+
+    # module-level symbol
+    mod_doc = ast.get_docstring(tree)
+    symbols.append(DocSymbol(
+        path=rel, qualname="", kind="module", name=Path(rel).stem, lineno=1,
+        is_public=True, has_docstring=mod_doc is not None,
+        docstring_len=len(mod_doc or ""),
+    ))
+
+    def walk(nodes, prefix: str, inside_class: bool) -> None:
+        for node in nodes:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                kind = "method" if inside_class else "function"
+                _add(node, kind, prefix)
+                # nested functions/classes
+                walk(node.body, f"{prefix}{node.name}.", inside_class=False)
+            elif isinstance(node, ast.ClassDef):
+                _add(node, "class", prefix)
+                walk(node.body, f"{prefix}{node.name}.", inside_class=True)
+
+    def _add(node, kind: str, prefix: str) -> None:
+        doc = ast.get_docstring(node)
+        qual = f"{prefix}{node.name}"
+        symbols.append(DocSymbol(
+            path=rel, qualname=qual, kind=kind, name=node.name, lineno=node.lineno,
+            is_public=is_public(node.name), has_docstring=doc is not None,
+            docstring_len=len(doc or ""),
+        ))
+
+    walk(tree.body, prefix="", inside_class=False)
+    return symbols, None

tessera_docs/schema.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class DocSymbol(BaseModel):
+    """A documentable Python symbol. Serialized to ``symbols.jsonl``."""
+
+    path: str            # repo-relative source file, POSIX
+    qualname: str        # dotted name within the module (module-level = "")
+    kind: str            # module / class / function / method
+    name: str
+    lineno: int = 0
+    is_public: bool = True
+    has_docstring: bool = False
+    docstring_len: int = 0
+    metadata: dict[str, Any] = Field(default_factory=dict)

tessera_docs/validator.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any
+
+from tessera_core.models import ValidationFinding
+
+from tessera_docs.schema import DocSymbol
+
+LOW_COVERAGE_THRESHOLD = 0.80
+
+
+def validate_docs_records(symbols: list[DocSymbol], options: dict[str, Any]) -> list[ValidationFinding]:
+    findings: list[ValidationFinding] = []
+
+    for err in options.get("_parse_errors", []):
+        findings.append(
+            ValidationFinding(severity="error", code="parse_error",
+                              message=f"could not parse: {err}", field=None)
+        )
+
+    public = [s for s in symbols if s.is_public]
+    if not public:
+        if not options.get("_parse_errors"):
+            findings.append(ValidationFinding(severity="info", code="no_public_symbols",
+                                              message="no public symbols found", field=None))
+        return findings
+
+    code_for_kind = {
+        "module": "missing_module_docstring",
+        "class": "missing_class_docstring",
+        "function": "missing_function_docstring",
+        "method": "missing_method_docstring",
+    }
+    severity_for_kind = {
+        "module": "info",
+        "class": "warning",
+        "function": "warning",
+        "method": "warning",
+    }
+
+    for s in public:
+        if not s.has_docstring:
+            findings.append(
+                ValidationFinding(
+                    severity=severity_for_kind.get(s.kind, "warning"),
+                    code=code_for_kind.get(s.kind, "missing_docstring"),
+                    message=f"{s.kind} `{s.qualname or s.name}` ({s.path}:{s.lineno}) has no docstring",
+                    field="docs",
+                    metadata={"path": s.path, "qualname": s.qualname or s.name, "kind": s.kind, "lineno": s.lineno},
+                )
+            )
+
+    documented = sum(1 for s in public if s.has_docstring)
+    coverage = documented / len(public)
+    if coverage < LOW_COVERAGE_THRESHOLD:
+        findings.append(
+            ValidationFinding(
+                severity="warning", code="low_doc_coverage",
+                message=f"public docstring coverage is {coverage*100:.0f}% (below {int(LOW_COVERAGE_THRESHOLD*100)}%)",
+                field="docs", metadata={"coverage": round(coverage, 4)},
+            )
+        )
+
+    return findings

tesserakit_docs-0.4.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: tesserakit-docs
+Version: 0.4.0
+Summary: Docs job pack for Tessera: measure Python docstring coverage for public symbols.
+Project-URL: Homepage, https://github.com/ShaileshRawat1403/tessera
+Project-URL: Repository, https://github.com/ShaileshRawat1403/tessera
+Project-URL: Issues, https://github.com/ShaileshRawat1403/tessera/issues
+Author: Shailesh Rawat
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: tesserakit-core>=0.1.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tesserakit-docs
+
+Measure Python docstring coverage for public symbols.
+
+`tessera-docs` parses Python source with the standard-library `ast` module (it never imports or runs the code), inventories every documentable symbol (modules, classes, functions, methods), and reports which public ones lack docstrings.
+
+## Coverage check
+
+```bash
+tessera docs coverage --input . --output ./out/docs_pack
+tessera docs coverage --input . --include-tests   # also scan test files
+```
+
+Test files are excluded by default; pass `--include-tests` to include them.
+
+Artifacts written:
+
+```text
+symbols.jsonl            one DocSymbol per symbol (kind, public, has_docstring, line)
+index.md                 coverage headline
+validation_report.md     missing-docstring findings + low-coverage warning
+coverage_report.md       coverage by kind and lowest-coverage files
+undocumented.md          every undocumented public symbol with file:line
+```
+
+## What counts
+
+- **Public** = name does not start with `_` (so `_private` and `__dunder__` are excluded).
+- Symbol kinds: `module`, `class`, `function`, `method`.
+- A symbol is documented if `ast.get_docstring` returns a value.
+
+## Findings
+
+- `missing_module_docstring` (info)
+- `missing_class_docstring`, `missing_function_docstring`, `missing_method_docstring` (warning)
+- `low_doc_coverage` — overall public coverage below 80%
+- `parse_error` — a file could not be parsed
+- `no_public_symbols` — nothing public found

tesserakit_docs-0.4.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+tessera_docs/__init__.py,sha256=lOU_jR1sGVZe8D1lbLDFa_u4C1SGz-s021MYlwke8pc,48
+tessera_docs/cli.py,sha256=Xt5Ci_N3U5hbeth_D2shuT_W4I9aN5Eb8b7CgpWwH2Q,1619
+tessera_docs/compiler.py,sha256=jTk4rbe7HBNVRvCJQNRTuuqvPv7kDj_pvgWfRW9Q24I,5694
+tessera_docs/loader.py,sha256=eF4UXvmGEL7OgyGjJhwYd27Ko-hUrs8fOuH5vP4IjoA,900
+tessera_docs/pack.py,sha256=wgJBaLPrzbOkVqD80GsEnm_RKY5WGGlNZRd-GEgNuKo,910
+tessera_docs/scan.py,sha256=oPDW_8vh33pcSGaeAJ5Bin83bvlJs50k_Wco9DH8VxI,2819
+tessera_docs/schema.py,sha256=_zUGhJodAkHte3M8KQe6bISqMl8HnpnWxq8VHLXuBTc,580
+tessera_docs/validator.py,sha256=vTsB3Q_1B4Orwqq49AMG2yiCMtUU0_E9EEZlrAVGIcY,2293
+tesserakit_docs-0.4.0.dist-info/METADATA,sha256=iIF73PndfuUMAWw7OlMqvJ8x1MCwUrmWWhSvNyvELi4,2259
+tesserakit_docs-0.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tesserakit_docs-0.4.0.dist-info/entry_points.txt,sha256=n6X0ZZpenfXtDacASPce_62cOWcDHKjvuBnuiQdGfMk,109
+tesserakit_docs-0.4.0.dist-info/RECORD,,

tesserakit_docs-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

tesserakit_docs-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[tessera.commands]
+docs = tessera_docs.cli:register
+
+[tessera.jobpacks]
+docs = tessera_docs.pack:create_pack