Users are confused what unit(s) of Dart are signficant

[matanlurey]

Forked from the discussion in dart-lang/language#11.

We have, 6, maybe 7 different ways of expressing a "unit of Dart code" as-of Dart 2.0:

• Files (i.e. on disk, a file.dart), until Recognize file entry-points that should be accessed as package URIs #33076 is fixed?
  • Package files (i.e. loaded via package:name/file.dart and .packages spec)
• Libraries (i.e. a file with optionally 1 or more part files contributing to it)
• Packages (i.e. package:name with a pubspec.yaml file and lib/ folder)
  • Tests (i.e. the test/ folder of a package)
• Bazel Targets (with some overlap with package, but other differences - such as subset of sources and dependencies where-as packages encapsulate all files in lib/ and the union of all of their dependencies). I imagine this also overlaps with GN/Ninja for the SDK and Fuischa to some extent.
• Build Modules (i.e. how build_runner determines incremental builds for DDC and the VM/Kernel)

... some of these units are only understood by certain tools:

Tool	File	Libraries	Packages	Tests	Targets	Modules
Analyzer	✅	✅	✅	✅	❌	❌
package:meta	✅	✅	✅	✅	❌	❌
package:linter	✅	✅	✅	✅	❌	❌
DDC	✅	✅	❌	❌	❌	❌
Dart2JS	✅	✅	❌	❌	❌	❌
Dart VM	✅	✅ ☆	❌	❌	❌	❌
CFE	✅	✅	❌	❌	❌	❌
package:build	✅	✅	✅	✅	✅	✅
Bazel Rules	✅	✅	✅	✅	✅	❌

☆ ⚠️See #33076 for how the VM differs from other tools in this regard

This had made it exceedingly difficult to:

• Help inform users the best way to structure code for faster incremental compile
• Help inform users the best way to structure code to avoid extraneous dependencies
• Help build tools that perform modular analysis and computation in a uniform way
• Help build tools that return accurate results for all environments
  • For example the analyzer allows importing files that are not visible to a target in Bazel
• Instruct changes to the language or tools around the concept of visibility across units
  • See sealed, protected, etc

/cc @bwilkerson, @srawlins who are very passionate about this topic.

[srawlins]

This would be a great soft spot in the underbelly of Dart to firm up with some armor, a la best-practices documentation, allowing the term "package" into the language spec for concepts like visibility, and maybe some language features like "package-private" declarations and "friend" libraries. Further reading:

• issue regarding testing private APIs; I suggest "friend libraries" there.
• @protected
• @visibleForTesting which uses URIs to make decisions
• @visibleForTemplate issue
• The linter's implementation_imports rule
• linter request for unused, unexposed public members (impossible to tackle code bloat without rigid notions of a "package" and its "public API.")

[lrhn]

There are actually two different notions of packages: Pub packages and language packages.

The one you list (pubspec.yaml and lib dir) is the pub package. The language never sees that, it only sees "the collection of files at the end of a package:packageName/ URI" (the "package files") as a package.
If the language introduces "package" as a concept in the specification, the language package is what it will have to work with, not the pub package.

(You could argue that "language packages" is not really a concept at all, because it has no effect on anything, but at least there is some logic included in the package URI handling).

[matanlurey]

@lrhn:

... the language package is what it will have to work with, not the pub package.

Unfortunately, that would what preclude anything that understands the test/ folder, for example.