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