fix(dart): an annotation links the constant or constructor it names, even behind a comment

[colbymchenry]

Summary

Two Dart decorates bugs, fixed in that order.

Resolution: annotations went to a method or function by name. A Dart annotation is a constant expression: a reference to a const variable (@riverpod, @override, @meta.immutable, a type's static constant or enum value) or a call of a const constructor (@Riverpod(keepAlive: true), @Foo.named(…)). decorates refs were ranked like Python decorators (+25 for a function or method, +15 for a class, nothing for a constant). On rrousselGit/riverpod that sent all 506 @riverpod annotations to riverpod_analyzer_utils' extension getter RiverpodAnnotatedAnnotatedNodeOfX::riverpod (0.4) instead of riverpod_annotation's const riverpod = Riverpod();.

matchDartAnnotation (name-matcher.ts) now takes every Dart decorates ref first in resolveOneInner, with no fallthrough. It reads the annotation as written from its @, in comment-blanked source, and counts it as a call only when ( follows on the same line. It links:

• @x: on a member, a static constant or enum value of the type around it. Otherwise, a top-level constant the file's library can see, using fix(dart): a bare call or type name reaches only what its library can see #2386's model, where the own library shadows imports.
• @X(…): a visible class, not an extension.
• @p.x / @p.X(…): the same, through an import prefix. The new isDartImportPrefix in dart-libraries.ts checks the imports of the file's whole library.
• @T.x: T's own constant or enum value. @T.named(…) is T's named constructor, using fix(dart): index const constructors and redirecting factories; a call through a type stays on that type #2380's isDartConstructor. @p.T.… works the same through a prefix.
• Never a method, getter or function. One candidate links at 0.9. Several candidates can only occur where the library model can't establish the library; then it falls back to proximity at 0.7 / 0.4.

Extraction: a comment hid the annotation. extractDecoratorsFor's preceding-sibling scan (scan #2) stopped at the first sibling that wasn't an annotation. So in @override // ignore: must_call_super void f(), @x /// Doc below. void f(), or riverpod_lint's @riverpod // expect_lint: … fixtures, the annotation attached to nothing. In Dart an annotation always belongs to the next declaration, so the Dart-only extractor field decoratorStepOverTypes: ['comment', 'documentation_comment'] makes the scan step over both comment kinds. The kernel twin is DECORATOR_STEP_OVER in dart.rs's extract_decorators_for. No other language sets it.

Validation

Validated on rrousselGit/riverpod @4ba1be2 and felangel/bloc @b9be1e2, with the kernel loaded, against main at 631df01. The diff keys edges by (source, target, kind, line, col, metadata):

	riverpod	bloc
decorates edges retargeted	506 (@riverpod: getter 0.4 → const riverpod 0.9)	0
edges added	16 (@riverpod behind a comment → const riverpod)	0
edges removed	0	0
decorates refs added	54 on 48 declarations (@override 32, @internal 6, @riverpod 16)	7 (all @override)
nodes, files	identical	identical

• Every other decorates edge is identical: riverpod's $internal, Riverpod, Dependencies, $mustCallSuper, JsonPersist, and so on.
• Every annotation the extractors record in both repos is written with a single name, so the prefixed and T.x forms are covered only by the new test.
• An earlier AST scan counted 55 hidden riverpod annotations. The 55th is @override on a field, and no Dart extractor records fields.
• Kernel and wasm full-index dumps are byte-identical on both repos.
• scripts/kernel-parity.mjs --lang dart --max-deferral 0.3 reports 0 diffs: bloc 595/616 and riverpod 1037/1303, with the deferred files being the usual parse-error ones.
• Timing: resolving riverpod's 12,061 decorates refs takes about 450 ms per warm round both before and after. Interleaved whole-index timings show no regression.

Tests

• __tests__/dart-annotation-targets.test.ts: resolution, end to end, on both backends. It covers the riverpod getter decoy, a function decoy, a constant the file can't see, prefixed @meta.…, a named constructor, a static constant, an enum value, a member's enclosing static constant, a private constant across part, and an annotation behind a comment.
• __tests__/dart-annotation-comments.test.ts: extraction on kernel and wasm, with LF and CRLF line endings.
• New parity fixture TortureAnnotatedComments.dart.
• Both new test files fail on unmodified main with main's kernel (6/6 tests fail).
• CODEGRAPH_KERNEL_EXPECT=1: the Dart, parity, resolution and extraction suites pass (22 files, 1,054 tests).
• Full suite: 6,240 passed and 80 skipped. 7 tests timed out under load in git-index-currency, mcp-status-freshness and oversize-file-not-read; all 20 tests in those files pass when run alone.

Docs: two [Unreleased] Fixes bullets in CHANGELOG, and docs/design/dart-kernel-port-checklist.md §Decorators updated (the scan #2 step-over and the new resolution rules).

Overlap

Open PR #2389 (Dart calls through an import prefix) adds dartImportPrefixes() to dart-libraries.ts. It answers the same question as isDartImportPrefix() here, and it also follows a part's part of parent where no pubspec is found. Whichever PR lands second should keep one helper. One way: isDartImportPrefix(file, name, context) becomes dartImportPrefixes(file, context).has(name), and then dart-annotation-targets.test.ts is re-run.

🤖 Generated with Claude Code