Crash when the source exports `package:flutter/material.dart`

[pedroleiterocha]

I have a private design system library which re-exports package:flutter/material.dart, while hiding some classes and providing alternatives for them. When trying run dart doc in my library, it crashes with dartdoc 8.2.0 (...) failed: UnimplementedError: No members on Library.sentinel are accessible. I can't share my library here, but I created a reproducible example in https://github.com/pedroleiterocha/dart_doc_test.

[srawlins]

Thanks for the reproduction! dartdoc 8.2.0 is rather old (published 10 months ago). Can you (a) say what version of dart you used (in your dart doc), and (b) try on a more recent release? I'm not sure what recent Dart/Flutter should have dartdoc 8.3.x, but maybe the latest beta release would be good to check.

[pedroleiterocha]

Hi! Thanks for the quick response! 😄

(a) Sure, it is Dart 3.6.1. It is the version used in the company I work for. It gets updated once or twice a year.

% dart --version 
Dart SDK version: 3.6.1 (stable) (Tue Jan 7 09:50:00 2025 -0800) on "macos_arm64"

(b) I've tried with Dart version 3.8.1, which has dartdoc 8.3.3. It crashes with the same outcome:

Documenting dart_doc_export_material...
Discovering libraries...
[-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------] (100.00%)

Linking elements...
[-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------] (100.00%)

Precaching local docs for 710295 elements...
[-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------] (100.00%)

Initialized dartdoc with 770 libraries
Generating docs for library dart_doc_export_material.dart from package:dart_doc_export_material/dart_doc_export_material.dart...

dartdoc 8.3.3 (/Users/pedro.rocha/Work/tmp/dart_doc_test/dartdev) failed: UnimplementedError: No members on Library.sentinel are accessible
#0      _LibrarySentinel.noSuchMethod (package:dartdoc/src/model/library.dart:19:7)
#1      _LibrarySentinel.element (package:dartdoc/src/model/library.dart:16:7)
#2      canonicalLibraryCandidate (package:dartdoc/src/model/canonicalization.dart:17:69)
#3      ModelElement.canonicalLibrary.<anonymous closure> (package:dartdoc/src/model/model_element.dart:514:11)
#4      ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart:529:4)
#5      ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart)
#6      PackageGraph.findCanonicalModelElementFor (package:dartdoc/src/model/package_graph.dart:742:32)
#7      DefinedElementType.isPublic (package:dartdoc/src/element_type.dart:303:22)
#8      IterableOfNameableExtension.wherePublic.<anonymous closure> (package:dartdoc/src/model_utils.dart:86:49)
#9      WhereIterator.moveNext (dart:_internal/iterable.dart:468:13)
#10     MappedIterator.moveNext (dart:_internal/iterable.dart:419:19)
#11     WhereTypeIterator.moveNext (dart:_internal/iterable.dart:904:20)
#12     Constructable.extraReferenceChildren (package:dartdoc/src/model/inheriting_container.dart:35:14)
#13     Container.referenceChildren (package:dartdoc/src/model/container.dart:205:8)
#14     _rejectUnnamedAndShadowingConstructors (package:dartdoc/src/markdown_processor.dart:151:10)
#15     CommentReferable._recurseChildrenAndFilter (package:dartdoc/src/model/comment_referable.dart:159:23)
#16     CommentReferable._lookupViaScope (package:dartdoc/src/model/comment_referable.dart:144:12)
#17     CommentReferable.referenceBy (package:dartdoc/src/model/comment_referable.dart:58:20)
#18     _getMatchingLinkElement (package:dartdoc/src/markdown_processor.dart:176:15)
#19     getMatchingLinkElement (package:dartdoc/src/markdown_processor.dart:187:16)
#20     MarkdownDocument._makeLinkNode (package:dartdoc/src/markdown_processor.dart:313:18)
#21     new MarkdownDocument.withElementLinkResolver.<anonymous closure> (package:dartdoc/src/markdown_processor.dart:267:51)
#22     LinkSyntax._resolveReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:137:36)
#23     LinkSyntax._tryCreateReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:177:18)
#24     LinkSyntax.close (package:markdown/src/inline_syntaxes/link_syntax.dart:103:12)
#25     InlineParser._linkOrImage (package:markdown/src/inline_parser.dart:150:32)
#26     InlineParser.parse (package:markdown/src/inline_parser.dart:106:9)
#27     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:298:67)
#28     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:303:9)
#29     MarkdownDocument.parseMarkdownText (package:dartdoc/src/markdown_processor.dart:288:5)
#30     Documentation._parseDocumentation (package:dartdoc/src/model/documentation.dart:83:21)
#31     Documentation._renderDocumentation (package:dartdoc/src/model/documentation.dart:64:23)
#32     Documentation.asOneLiner (package:dartdoc/src/model/documentation.dart:58:5)
#33     ModelElement.oneLineDoc (package:dartdoc/src/model/model_element.dart:731:49)
#34     _renderCategory_partial_container_3 (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:2965:25)
#35     renderLibrary (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:968:20)
#36     HtmlAotTemplates.renderLibrary (package:dartdoc/src/generator/templates.dart:178:30)
#37     GeneratorBackend.generateLibrary (package:dartdoc/src/generator/generator_backend.dart:186:29)
#38     HtmlGeneratorBackend.generateLibrary (package:dartdoc/src/generator/html_generator.dart:80:11)
#39     GeneratorFrontEnd._generateDocs (package:dartdoc/src/generator/generator_frontend.dart:158:27)
#40     GeneratorFrontEnd.generate (package:dartdoc/src/generator/generator_frontend.dart:37:25)
<asynchronous suspension>
#41     Dartdoc.generateDocsBase (package:dartdoc/src/dartdoc.dart:203:5)
<asynchronous suspension>
#42     Dartdoc.generateDocs (package:dartdoc/src/dartdoc.dart:241:24)
<asynchronous suspension>
#43     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/src/dartdoc.dart:273:9)
<asynchronous suspension>

[srawlins]

Thanks so much for checking!

[szakarias]

Thanks for filing this issue.

The root cause is in how we handle doc imports. We can reproduce the crash simply by creating a Dart project with dart create, adding a doc import for a package, and then referencing a member from it. E.g.

/// @docImport 'package:collection/collection.dart';
library;

/// I love [IterableExtension]
int calculate() {
  return 6 * 7;
}

The permanent fix requires changes to the Dart analyzer. Until then, you should be able to work around the issue by adding import 'package:flutter_test/flutter_test.dart'; to your project. This should allow dart doc to run without crashing.

[sigurdm]

Interesting - I don't think package:collection is an sdk package. It is a normal package (as opposed to dart:collection!)

[szakarias]

Sorry, it shouldn't have said SDK, it can be any package.

[srawlins]

The permanent fix requires changes to the Dart analyzer.

I lost the thread on this one, @szakarias can you elaborate on what needs to be fixed in the analyzer code?

[szakarias]

The overall problem is that libraries are not properly resolved for doc imports. 

I think one approach in the analyzer could be to set the libraryImport element on doc imports here like we do for regular imports here.