feat(orm): with_count() correlated relationship counts

[tmgbedu]

Summary

Implements end-to-end with_count() (Laravel withCount) on the async ORM — the feature was previously unwired (BaseRelationship.get_with_count_query was NotImplementedError and the *Through/BelongsToMany overrides chained on the async count() coroutine, so nothing worked).

users = await User.query().with_count("articles").get()
users[0].articles_count            # -> int
User.query().with_count("articles", lambda q: q.where("published", 1))   # constrained count

Changes

• QueryBuilder.select_count(column="*", alias=None) — synchronous COUNT aggregate builder (the query-building counterpart to the async count()), used to compose correlated COUNT subqueries.
• QueryBuilder.with_count(relation, callback=None) + Model.with_count(...) — adds a correlated (SELECT COUNT(*) ...) AS {relation}_count column; the optional callback constrains the count subquery.
• BaseRelationship.get_with_count_query — real default for direct relations (HasMany/HasOne/BelongsTo).
• BelongsToMany / HasOneThrough / HasManyThrough — with-count subqueries now build the COUNT synchronously via select_count() (fixes the async-count() blocker, no un-awaited coroutine).
• BelongsToMany __init__ — fixed the resolver lambda (it took a spurious arg, breaking get_builder()), so its correlated queries resolve.
• Relabelled three factory/collection tests whose names misleadingly contained with_count.

Tests

tests/masoniteorm/sqlite/builder/test_sqlite_with_count.py — real sqlite end-to-end asserting actual counts for all four relationship types:

• HasMany (Joe=1, Jane=0), HasManyThrough (1/0), HasOneThrough (all=1), BelongsToMany (store1=2, store2=0).
• 0-related → 0; callback-constrained count; base-column seeding; Model.with_count classmethod; correlated-subquery SQL shape.

Fixtures use the ORM (Schema builder + Model.insert), not raw SQL.

Gates

• uv run pytest --ignore=tests/masoniteorm/postgres --cov → 1829 passed / 7 skipped, coverage 79.23% (≥ fail_under 68).
• ruff check + ruff format --check clean.

⚠️ Stacked PR

This branch is stacked on #170 (select_sub/add_select, which provides select_sub + table() + the migrated with-count call shape). The diff against main therefore includes #170's commit until it merges. Review/merge order: #170 first, then this. The with_count-specific commit is the top one (feat(orm): with_count() correlated relationship counts).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[tmgbedu]

✅ Code Review: APPROVE (do not merge — stacked on #170; merge order #168→#169→#170→#171)

Posting as a comment — GitHub blocks a formal approve on one's own PR.

Reviewed the top with_count commit (1384ecb) in isolation from the #170 base. Correctness, patterns, and test quality all hold up.

Correctness — verified independently

• Correlated COUNT SQL is right. get_with_count_query builds related.select_count("*").where_column(f"{related_table}.{foreign_key}", f"{owner_table}.{local_key}") → (SELECT COUNT(*) FROM articles WHERE articles.user_id = users.id) AS articles_count. Confirmed by the SQL-shape test and real end-to-end counts (Joe=1 / Jane=0) — it executes correctly on sqlite, not just plausible-looking.
• Base-column seeding. if not builder._columns: builder.select("{table}.*") before select_sub — verified by test_has_many_count_seeds_base_columns.
• The 3 Through/pivot overrides now compose COUNT synchronously via select_count("*") instead of chaining on the async count() coroutine — the #886 blocker. No un-awaited coroutine remains; all three return real counts.
• BelongsToMany __init__ resolver fix is legitimate. get_builder() is self.fn()().get_builder() — calls self.fn() with no args, so the old lambda x: raised TypeError. The fix lambda: registry.Registry.resolve(fn) matches the BaseRelationship convention (line 9) and drops the accidental double-assignment.

Pattern consistency

• with_count mirrors where_has/or_where_has exactly; select_count mirrors the existing aggregate/count shape. Model.with_count follows the with_/where delegation style. New code belongs.

Tests

Real sqlite, ORM-first fixtures (Schema + Model.insert), no hollow mocks — meets the PR #159 bar. Asserts actual counts across all four relationship types, plus 0-count→0, callback-constrained (1/0) and callback-excluding-all (0/0), classmethod, and correlated-subquery SQL shape. The three misleadingly-named factory/collection tests correctly relabeled (behavior unchanged).

Gates reproduced locally

• test_sqlite_with_count.py: 9 passed.
• models + sqlite + query suites: 397 passed / 6 skipped, no regressions.
• ruff check + ruff format --check: clean.

Non-blocking note

Relationships declared without explicit keys (relying on set_keys convention defaults) would produce NULL-keyed correlation in with_count, since set_keys isn't invoked on class-level attribute access. This is a pre-existing limitation shared verbatim by where_has/has (same getattr(...class..., relation) path) — not introduced here; all fixtures/real usage pass explicit keys. Follow-up candidate, not a blocker.

LGTM. Merge left to PM per the stack order.