fix: annotate the query views with the classes they return (#328)

[livingstaccato]

Fixes #328.

What

BodyView.blocks() and .attributes(), and their DocumentView and BlockView delegates, were annotated List[NodeView]. Each only ever returns the concrete class, so under a strict type checker block_type, labels, name_labels and AttributeView.name needed an isinstance narrowing or a cast for a runtime type that is never anything else. They now say List[BlockView] / List[AttributeView], and BlockView.body says BodyView.

Why the second commit exists

Naming those classes as forward references is not enough on its own. typing.get_type_hints resolves an annotation against the defining function's own globals, and the view classes were imported inside each method to break the body <-> blocks import cycle. So every narrowed annotation raised NameError for anything that introspected it -- pydantic, a docs builder, a runtime validator -- while the previous NodeView annotation resolved fine, since that one is imported at module level.

AttributeView has no cycle and moves to a plain top-level import. BodyView and BlockView do name each other, so each module imports the other at the bottom, after its own classes exist: the name lands in module globals, and neither import can run before the classes are defined. Verified under all three import orders.

Tests

test/unit/query/test_view_annotations.py asserts the annotations rather than the runtime types, because a runtime check passed before the change too. They call get_type_hints bare -- an earlier draft passed a hand-built localns, which supplied exactly the names that were missing and so could not see the problem. Against the tree without the second commit, those tests produce 18 errors.

Compatibility

Return values are unchanged; this narrows declarations and moves two imports.

It is a static break for one shape of caller, and the earlier wording here got that wrong. list is invariant, so views: List[NodeView] = document.blocks() stops type-checking even though BlockView is a NodeView -- mypy reports Incompatible types in assignment (expression has type "list[BlockView]", variable has type "list[NodeView]"). Runtime behaviour is identical, and the fix for such a caller is to narrow the annotation or drop it. Annotating the return as Sequence[BlockView] would keep those callers compiling, but it would also remove append and friends from the declared contract, which is a bigger decision than this PR should make on its own.

Merging

Up to date with main as of 2f6d718, by merging rather than rebasing (the merge=union CHANGELOG duplicates entries under a rebase).

It merges cleanly on its own, and all twelve open PRs are merged together, with the full suite passing on 3.8-3.14, at livingstaccato/python-hcl2@int/pyvider-hcl-9. Landing alongside the others needs one small follow-up from whichever lands second:

• fix: annotate the query views with the classes they return (#328) #332 + fix: emit block line numbers when with_meta is set (#291) #333 edit adjacent lines in hcl2/query/blocks.py; keep both.

---

This pull request, and the investigation behind it, were produced by an AI assistant (Claude) working on behalf of the author. Please review with that provenance in mind.

[livingstaccato]

Please hold off on merging this one for now — I want to do another review pass over it before it goes in. Opened as a draft for that reason; I will mark it ready and say so here once I am done.

[livingstaccato]

Review pass done, so the hold above no longer applies — this is ready for review now.

Rebased on current main; GitHub reports it mergeable as it stands.

_{🤖 Drafted with Claude Code.}

[livingstaccato]

hi there! i hope you're okay with this torrent of issues and PRs. if you'd rather me submit things/work through things differently please just let me know and i'll tweak my workflow. thanks for this project! :)

[livingstaccato]

Hi @kkozik-amplify, thank you for your patience while I worked through this batch. It landed all at once at the start of the month, and I'd rather work to your pace than keep adding to it.

Since then I've tidied all twelve PRs:

• Two more review passes, with every change checked against OpenTofu 1.12.6. Where that turned up problems, the fixes went into the PR they belong to rather than new ones.
• Each branch is up to date with main (merged, not rebased), and each merges cleanly on its own.
• The descriptions are updated to match. Several had drifted as the fixes changed, and none of them offers a rebase any more.
• All twelve merged together are at livingstaccato/python-hcl2@int/pyvider-hcl-9, passing the full suite on Python 3.8-3.14. Each description lists the few spots where landing two of them needs a small follow-up.

If a suggested order helps, smallest and most independent first:

1. Standalone fixes: fix: annotate the query views with the classes they return (#328) #332, fix: force_operation_parentheses works under a parenthesised ancestor (#342) #348, fix: a heredoc closing marker may carry trailing whitespace (#343) #349, fix: stop concurrent parses from sharing one serialization context (#327) #334, fix: two rules that ignored they were writing expression source (#340, #341) #350, fix: heredocs_to_strings writes a value, not the heredoc's text (#337) #351, fix: emit block line numbers when with_meta is set (#291) #333.
2. The heredoc stack: fix: return heredoc bodies that match what Terraform evaluates (#326) #335, then fix: escapes belong to the span they are written in (#329, #336, #339) #346, then fix: decline to flatten a heredoc whose interpolation spans lines (#347) #354, with fix: a heredoc ends its own line wherever it is written (#338) #352 alongside fix: return heredoc bodies that match what Terraform evaluates (#326) #335. They're stacked, so each carries the one before it, and they're the largest.
3. feat: carry serializer metadata beside the mapping (#331) #345, the metadata sidecar, last. It adds an option rather than fixing a bug, so it's the one I'd most like your view on before you read the code.

I'd also welcome any guidance for the future, both on contributing and on helping with issues. I've read your contributing guide in #321, and in hindsight I should have waited for agreement on the approach in each issue before opening PRs. Going forward I'm glad to work however suits you: discuss first and one PR at a time, or take only issues you point me at. The same goes for this batch. I'm happy to close anything you'd rather not take, split the larger heredoc PRs, or hold the rest until you've had a chance to look.

Thanks again.