tom_analyzer_shared library

Shared analyzer-summary caching infrastructure for Tom code generators.

This library exposes:

See the package README for motivation and examples.

Classes

AnalyzerCacheGarbageCollector
Opt-in garbage collector for orphaned analyzer-cache partitions.
AnalyzerCachePartition
One <analyzer-major>/<toolchain> partition in the shared cache.
CacheStats
Statistics about the summary cache.
DependencyResolver
Resolves project dependencies with their versions from pubspec.lock.
DependencySet
Groups dependencies by their cacheability status.
GroupedPackageBundle
Result of building a grouped packages.sum bundle from several package closures.
GroupedPackageBundleBuilder
Builds one packages.sum bundle from the union of several package dependency closures.
PackageDependency
Represents a resolved package dependency with version information.
SummaryCacheManager
Manages the analyzer summary cache for a workspace.
SummaryCacheResult
Result of a summary-cache stage execution.
SummaryGenerationResult
Result of generating summaries for a batch of packages.
SummaryGenerator
Generates analyzer summaries for packages.
SummaryStamp
What a summary file was written by, recorded in a stamp file beside it (<summary>.stamp): the toolchain (currentToolchainKey: the Dart SDK and the analyzer data version, the exact key of the summary format) and whether it was built with Flutter's embedder (dart:ui). The embedder is recorded by its presence, not its path: the Dart SDK version in the toolchain already names the Flutter release it ships with, and a path would make the stamp — committed beside a shipped summary — true on one machine only.
SweptCacheFile
A file AnalyzerCacheGarbageCollector.sweepBundles removed (or, on a dry run, would remove).
ToolCacheLocator
Resolves the Tom tool-cache directory — a workspace-local location for build artefacts that can be reused across the projects and tools of a single workspace.

Extensions

DependencyListExtensions on List<PackageDependency>
Extension methods for working with dependency lists.

Constants

analyzerDataVersion → const int
The data version of the analyzer this build is linked with (AnalysisDriver.DATA_VERSION): the analyzer raises it whenever what it stores — summary bundles among it — changes format.
analyzerMajorVersion → const int
The major version of the analyzer package this build of tom_analyzer_shared was compiled against.

Functions

analyzerDataVersionInPackageRoots(Map<String, String> packageRoots) → int?
The data version of the analyzer resolved among packageRoots (name → package root, as readPackageRoots returns them), read from its AnalysisDriver source, or null when the packages resolve no analyzer or the constant cannot be found. Tells whether summaries this tool writes can be read by the analyzer another package (an app shipping them) runs on.
currentDartSdkVersion() → String
The <major>.<minor>.<patch> Dart SDK version of the running toolchain.
currentToolchainKey({String? dartSdkVersion, int? dataVersion}) → String
The toolchain a summary was written by, as one path-safe key: <dart-sdk-version>+d<analyzer-data-version> (e.g. 3.13.7+d752). The second segment of the cache partition, and what a stamp beside a summary records. Both parts default to the running toolchain.
dartSdkWithEmbedder(ResourceProvider resourceProvider, {required String sdkPath, String? embedderYamlPath}) → FolderBasedDartSdk
The Dart SDK at sdkPath with the libraries of the embedder at embedderYamlPath added where the SDK lacks them — the same SDK buildSdkSummary(embedderYamlPath: ...) summarises, for linking a package summary that is read against that SDK summary. Without embedderYamlPath it is the plain SDK.
flutterEmbedderYamlInPackageRoots(Map<String, String> packageRoots) → String?
The embedder file of the sky_engine package among packageRoots (name → package root, as readPackageRoots returns them): the embedder of the very Flutter the packages were resolved against. Null when the packages are no Flutter packages.
flutterEmbedderYamlInSdk(String flutterSdkPath) → String?
The embedder file of the Flutter SDK at flutterSdkPath (bin/cache/pkg/sky_engine/lib/_embedder.yaml), or null when it has none.
looksLikeDartSdk(String? dir) → bool
Whether dir looks like a Dart SDK root.
mergePackageRootsForDirs(Iterable<String> packageDirs) → Map<String, String>
Merges the package roots resolved from each given package directory's .dart_tool/package_config.json into a single name→root map.
readPackageRoots(File packageConfigFile) → Map<String, String>
Reads a resolved .dart_tool/package_config.json and returns a map of package-name → absolute package root directory (the directory that contains lib/).
resolveDartSdkPath() → String?
Resolves the Dart SDK root directory, or null to let the analyzer fall back to its default (executable-relative) detection.
runSummaryCacheStage(String projectRoot, {bool verbose = false, bool rebuildCache = false, bool showCacheStatus = false, List<String> cacheOnlyPackages = const [], void log(String message)?, SummaryCacheManager? cacheManager}) → Future<SummaryCacheResult?>
Runs the summary-cache stage for a project.
summaryLibraryUris(Uint8List summaryBytes) → List<String>
The library URIs a summary holds (dart:core, dart:ui, package:flutter/painting.dart ...): whether an SDK summary holds dart:ui, i.e. was built with Flutter's embedder, without the analyzer's internals at the caller.

Exceptions / Errors

IncompleteSummaryException
A package's summary could not be built completely, so it was not cached.
SummaryConfigException
Raised when a package directory has no resolved .dart_tool/package_config.json (i.e. pub get has not been run there), or when a grouped bundle cannot be built (no SDK / no libraries).