Type completeness workflow

[genedan]

Summary of Changes

Add workflow for type completeness coverage report.

Runs pyright --verifytypes chainladder --ignoreexternal to generate a type completeness coverage report. GitHub actions then uses this information to create a summary table and generates a comment on the PR.

Related GitHub Issue(s)

#939

Additional Context for Reviewers

• I passed tests locally for both code (uv run pytest) and documentation changes (uv run jb build docs --builder=custom --custom-builder=doctest)

---

Note

Low Risk
Changes are limited to new CI scripts and workflows; no application or library runtime behavior is modified.

Overview
Adds CI on every pull request that runs pyright --verifytypes on the chainladder package at PR head and at the merge-base chainladder tree, then compares exported-symbol typing (known / ambiguous / unknown).

A new type_completeness.py script turns paired JSON reports into Markdown: project-wide completeness at head, docstring/default-param gaps, and a patch section for symbols whose export typing changed or were de-exported. A shell helper appends truncated full text output to GITHUB_STEP_SUMMARY so large reports do not blow the 1MiB cap.

type_completeness.yml uploads summary.md and the PR number as an artifact; type_completeness_comment.yml runs on workflow_run success and posts/updates a sticky PR comment via split permissions (read on the main job, pull-requests: write on the comment job) so fork PRs stay safe.

^{Reviewed by Cursor Bugbot for commit f4abd33. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Pyright Type Completeness

View the full pyright --verifytypes output for this commit

Project (full chainladder package, at this PR's head): 10.2% of exported symbols fully typed (121 / 1190)

	Known	Ambiguous	Unknown	Total
Project (head)	121	89	980	1190

Other symbols referenced but not exported by chainladder: 2308

	Known	Ambiguous	Unknown	Total
Other (head)	2056	76	176	2308

Symbols without documentation:

• Functions without docstring: 780
• Functions without default param: 52
• Classes without docstring: 182

Patch (exported symbols added or changed by this PR): no exported symbol type-completeness changes detected.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.35%. Comparing base (6aacc83) to head (f4abd33).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1042   +/-   ##
=======================================
  Coverage   89.35%   89.35%           
=======================================
  Files          89       89           
  Lines        5169     5169           
  Branches      661      661           
=======================================
  Hits         4619     4619           
  Misses        386      386           
  Partials      164      164           

Flag	Coverage Δ
unittests	89.35% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b8cebdd. Configure here.}

[henrydingliu]

about a page and half down in the detailed report, I see the following. Are they invocations of numpy in our package? Or actual numpy source code that we are importing? If it's the latter, should we try to exclude?

numpy.ndarray.__new__
  /home/runner/work/chainladder-python/chainladder-python/.venv/lib/python3.14/site-packages/numpy/__init__.pyi:2031:9 - error: Type of parameter "dtype" is partially unknown
    Parameter type is "type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None"
numpy.dtype.__new__
  /home/runner/work/chainladder-python/chainladder-python/.venv/lib/python3.14/site-packages/numpy/__init__.pyi:1505:9 - error: Type of parameter "dtype" is partially unknown
    Parameter type is "type[slice[Any, Any, Any]] | type[Decimal] | type[Fraction] | type[UUID] | type[date] | type[time] | type[timedelta] | type[tzinfo] | type[tuple[Any, ...]] | type[list[Any]] | type[set[Any]] | type[frozenset[Any]] | type[dict[Any, Any]] | type[object_]"
  /home/runner/work/chainladder-python/chainladder-python/.venv/lib/python3.14/site-packages/numpy/__init__.pyi:1505:9 - error: Type of parameter "dtype" is partially unknown
    Parameter type is "type[complex] | type[bytes] | type[str] | type[memoryview[int]] | type[slice[Any, Any, Any]] | type[Decimal] | type[Fraction] | type[UUID] | type[date] | type[time] | type[timedelta] | type[tzinfo] | type[tuple[Any, ...]] | type[list[Any]] | type[set[Any]] | type[frozenset[Any]] | type[dict[Any, Any]]"
decimal.Decimal.__ge__
  /home/runner/work/chainladder-python/chainladder-python/.venv/lib/python3.14/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/decimal.pyi:91:9 - error: Type of parameter "value" is partially unknown
    Parameter type is "Decimal | float | Rational"

[henrydingliu]

this also feels inflated to me: we may have a couple hundred no-docstring test functions, but I don't think we have more than couple dozen classes in the package in total, unless I'm misunderstanding 'class'.

Symbols without documentation:

Functions without docstring: 780
Functions without default param: 52
Classes without docstring: 182

[genedan]

I also noticed it was high. It turns out the first time I tried this, it was including dependencies. I added --ignoreexternal to only count the ones in chainladder.

The comment won't update until it gets merged though. Here are the updated stats when I ran it locally:

Symbols exported by "chainladder": 1190
  With known type: 148
  With ambiguous type: 106
  With unknown type: 936
    (Ignoring unknown types imported from other packages)

Other symbols referenced but not exported by "chainladder": 13
  With known type: 3
  With ambiguous type: 1
  With unknown type: 9

Symbols without documentation:
  Functions without docstring: 310
  Functions without default param: 0
  Classes without docstring: 10

Type completeness score: 12.4%

[genedan]

about a page and half down in the detailed report, I see the following. Are they invocations of numpy in our package? Or actual numpy source code that we are importing? If it's the latter, should we try to exclude?

Good question. The report is so overwhelming, it's hard for me isolate and figure out, kind of like the pytest warnings. I think a large number of these will resolve as we improve the type coverage of the package. Then we can isolate and hunt down what's left over.

For pytest, I asked Claude to pick the first test case that led to a warning, and resolved it. I'd use a similar technique for type errors.

When we do, I think we should fix the things we can fix, but suppress the ones we can't do anything about, documenting the reason why.

[henrydingliu]

The comment won't update until it gets merged though. Here are the updated stats when I ran it locally

okay. i think that's fine. would you mind putting a disclaimer into our PR template that says something to the effect of, we'd appreciate if you add type hinting in your PR; but once you create the PR, the typing stats won't update.