Remove legacy masoniteorm.backup + document ORM query-scopes state

[tmgbedu]

Summary

Task #774 — three parts: (1) document the ORM query-scopes feature and its state, (2) remove the legacy masoniteorm.backup duplicate, (3) investigate Loader.py.

1. Query-scopes feature — how it works & current state

Scopes live in the current ORM (masoniteorm/models/), not in a dedicated scopes/ package:

• Storage — Model._global_scopes = {} (models/model.py). On QueryBuilder.set_model() the dict is copied onto the builder (_global_scopes = model._global_scopes), and it's propagated to derived builders (e.g. the aggregate/count builder).
• Registration — the structure is {action: {name: callable}}, keyed by action (select, update, …). There is no public API to register a scope — no add_global_scope(), no scope_* method discovery/boot. _global_scopes is only ever initialised to {}, so in practice no global scope is ever populated.
• Application — QueryBuilder.run_scopes() iterates self._global_scopes.get(self._action, {}) and calls each scope(self). It runs from to_sql() and to_qmark() (i.e. at compile time). get() still has a literal # TODO: apply scopes.
• without_global_scopes() — called but never defined. It's invoked in 5 places in relationships/BelongsToMany.py (pivot select/attach/create paths), but no definition exists anywhere in the monorepo. Those pivot code paths would raise AttributeError if reached with the current builder.

State: partial / non-functional. The plumbing (_global_scopes, run_scopes) is in place, but there is no registration API, no local scope_* support, and without_global_scopes() is missing — so the feature is effectively inert and the BelongsToMany calls are latent bugs. A follow-up task is recommended to either implement without_global_scopes() + a registration API, or remove the dead scope plumbing and the BelongsToMany calls.

2. Removed legacy masoniteorm.backup

• Confirmed still git-tracked (59 files, 456K) — a full duplicate of the old ORM including its own scopes/, tests/, testing/.
• Grepped the whole monorepo (src, tests, example/*, application/, pyproject.toml) — nothing imports it. Its only reference was norecursedirs in pyproject.toml.
• Deleted the directory and removed the stale norecursedirs entry.

3. Loader.py investigation

• No Loader.py exists under masoniteorm/. The two Loader.py files are loader/Loader.py and facades/Loader.py.
• loader/Loader.py is actively used — imported by configuration/Configuration.py (Loader().get_modules(...) / get_parameters(...)) and exercised in tests. Kept — deleting it would break config loading.
• Nothing to delete here; reported for the record.

Verification

• uv run pytest --ignore=tests/masoniteorm/postgres --cov → 1777 passed, 7 skipped, coverage 78.56% (≥ 68% threshold). Postgres suite skipped (needs a live DB).
• uv run ruff check → all checks passed.
• uv run ruff format --check → 470 files already formatted.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!