fix(model): emit flat joins for belongsTo-chain nested includes (#3245)

[bpamiri]

Closes #3245

Problem

findAll(include="ParentModel(ChildModel)") regressed between Wheels 2 and 3: when the parenthesized intermediate is a plain belongsTo and the include mixes inner + outer joins, $fromClause wrapped the inner joins in a parenthesized group bound to the LEFT OUTER JOIN. That nested join expression scopes the root FROM table out of the inner join's ON clause, so MySQL rejects it with:

Unknown column 'relationships.relatedcontactid' in 'on clause'

The reporter's case: Relationship belongsTo SecondaryContact belongsTo User, called as findAll(include="RelationshipType,SecondaryContact(User)").

Root cause

vendor/wheels/model/sql.cfc $fromClause derived hasThroughAssociation purely from a regex on the include string (^([^(]+)\(([^)]+)\)$). Any Intermediate(Target) shape matched — including a belongsTo chain — so the issue #449 HABTM/through parenthesized-grouping heuristic over-fired. #449 introduced that grouping (commit 6579f246c, July 2025), which is why this is absent in Wheels 2.

Fix

Consult the association metadata instead of the string. When the single-paren pattern matches, look up the parenthesized intermediate association (ListLast of the text before () in variables.wheels.class.associations and only set needsNesting when its type is hasMany/hasOne — the OUTER-joined bridge the grouping was actually designed for. A belongsTo intermediate falls through to the existing flat-join branch (the Wheels 2 behavior).

Before (bug) vs after, for model("author").$fromClause(include="posts,user(galleries)"):

-- before: inner `users` join wrapped inside the OUTER group → root `authors` scoped out
FROM authors LEFT OUTER JOIN (posts INNER JOIN users ON authors.firstname = users.firstname) ON ... LEFT OUTER JOIN (galleries INNER JOIN users ON authors.firstname = ...) ON ...

-- after: flat sibling joins → every table in scope for every ON
FROM authors LEFT OUTER JOIN posts ON ... INNER JOIN users ON authors.firstname = users.firstname LEFT OUTER JOIN galleries ON users.id = galleries.userid

The genuine HABTM/through case (team → memberTeams(member), a hasMany bridge) still nests:

FROM teams LEFT OUTER JOIN (memberteams INNER JOIN members ON memberteams.memberid = members.id) ON teams.id = memberteams.teamid

Tests

Two regression specs added to the directly-callable $fromClause harness in vendor/wheels/tests/specs/model/crudSpec.cfc:

• belongsTo-chain nested include with a mixed inner/outer sibling asserts flat joins (MySQL nested include regression #3245).
• HABTM/through bridge include asserts the parenthesized grouping is preserved (JOINs should be grouped #449 does not regress).

Test status

Verified locally on SQLite (Lucee 7) and MySQL 9.7 (Lucee 7) — the engine in the report:

• crudSpec 163 pass / 0 fail / 0 error on both engines (includes both new regression specs).
• hasManyShortcutSpec (live HABTM/through/shortcut eager-load DB queries — JOINs should be grouped #449/model: hasMany shortcut= breaks the association entirely — $expandThroughAssociations misreads the shortcut through-chain as an include path (documented many-to-many pattern throws AssociationNotFound) #3109/hasMany shortcut association not recognised by include - "association not found" error #3208) 13/0/0 on both.
• Full wheels.tests.specs.model directory 923/0/0 on SQLite.

Cross-engine notes

Pure metadata read using StructKeyExists / ListFindNoCase / ListLast / Mid — no closures, reserved scopes, attributeCollection=arguments, obj.map(), or bare cfabort. The .type field is set on every association (belongsTo/hasMany/hasOne). Behavior is adapter-independent (the change only decides flat vs nested join structure); MySQL was the engine in the report and is verified green.

🤖 Generated with Claude Code