paginationLinks() is deprecated but emits no runtime warning and is not in MigrationScanner

[bpamiri]

Severity: medium — silent rot. 3.x → 4.0 upgraders don't know they're using a deprecated helper.

Surfaced by: titan Phase 2.4 (Wheels 4.0 upgrade), 2026-05-15.

Description

paginationLinks() is documented as deprecated in favor of paginationNav() (per #1930) but:

• vendor/wheels/view/links.cfc (where paginationLinks lives, around line 215) has no DeprecationLogger.log() call at the top.
• The legacy compatibility adapter (wheels-legacy-adapter@1.0.0) does not shim or warn on calls to paginationLinks.
• vendor/wheels/MigrationScanner.cfc does not include paginationLinks in its 3.x→4.0 scan rules, so wheels upgrade check doesn't flag apps that still use it.

The deprecation is purely a roadmap statement, invisible to anyone running a 3.x codebase forward into 4.0.

Suggested fix

Either or both:

1. Add DeprecationLogger.log(oldMethod=\"paginationLinks\", newMethod=\"paginationNav\") at the top of paginationLinks in vendor/wheels/view/links.cfc.
2. Add paginationLinks to MigrationScanner.cfc's 3.x→4.0 rule list so wheels upgrade check greps app code for paginationLinks( and flags hits.

cc @bpamiri

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

view — see .ai/wheels/views/ for canonical patterns. The deprecated helper lives in vendor/wheels/view/links.cfc (the paginationLinks function starts at line 215).

Fix sketch

Two related changes, both mechanical:

1. Runtime warning. Add a one-time deprecation warning at the top of paginationLinks in vendor/wheels/view/links.cfc:215. The repo does not currently expose a DeprecationLogger class — the existing pattern (see vendor/wheels/Plugins.cfc:559 $checkPluginsDeprecation()) is a one-time cflog(type="warning", text="...") guarded by a flag so the warning fires once per request/app, not on every render. Propose-fix should follow that pattern rather than inventing a new logger.
2. Upgrade-check coverage. The issue references MigrationScanner.cfc, but no file by that name exists in vendor/wheels/ — the closest thing is cli/src/commands/wheels/upgrade.cfc::checkBreakingChanges() plus vendor/wheels/tests/specs/cli/UpgradeCheckCoverageSpec.cfc. Propose-fix will need to confirm whether the scan rules live there (or in a sibling not-yet-named file referenced by that spec) and add paginationLinks( as a grep target with a remediation pointer to paginationNav().

The wheels-legacy-adapter@1.0.0 shim mentioned in the report lives in a separate repository (wheels-dev/wheels-legacy-adapter) and is out of scope for a framework-side fix.

Confidence: medium

The runtime-warning change is mechanical, but the MigrationScanner referenced in the issue does not exist by that name in the repo, so the upgrade-coverage half requires brief investigation before edits land.

<!-- wheels-bot:triage:2714 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2727

Spec: vendor/wheels/tests/specs/view/paginationLinksDeprecationSpec.cfc — failing → passing
Implementation: vendor/wheels/view/links.cfc (one-time per-request WriteLog warning, guarded by request.wheels.$paginationLinksDeprecationLogged), cli/lucli/Module.cfc (3.x → 4.x grep check for paginationLinks( in app/views/)

Note: this bot run could not execute bash tools/test-local.sh view locally (no wheels CLI on the runner) or bash tools/test-matrix.sh lucee7 sqlite (Docker access not approved for the harness in this environment), so the failing → passing transition is staged against the patterns it mirrors (UpgradeCheckCoverageSpec.cfc for the static check and paginationHelpersSpec.cfc for the controller-driven helper call). compat-matrix.yml on the PR is the authoritative pass-gate.

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.