tom_analyzer_shared library

Shared analyzer-summary caching infrastructure for Tom code generators.

This library exposes:

PackageDependency / DependencySet — resolved dependency metadata.
DependencyResolver — parses pubspec.lock and locates hosted/SDK package source trees in the pub cache and the Flutter SDK.
ToolCacheLocator — resolves the workspace-local Tom tool-cache directory (TOM_TOOL_CACHE → the workspace-root marker's .tom → <start>/.tom; never a machine-global directory).
SummaryCacheManager — reads and writes .sum files under the workspace tool cache's analyzer-cache/<analyzer-major>/ sub-directory.
analyzerMajorVersion — the analyzer major this build targets; used to partition the cache so analyzer upgrades cannot read stale bundles.
SummaryGenerator — generates the SDK summary and per-package summaries in topological order.
GroupedPackageBundleBuilder — builds one grouped packages.sum from the union of several package dependency closures (for embedded-editor runtime analysis). See mergePackageRootsForDirs / readPackageRoots.
runSummaryCacheStage / SummaryCacheResult — a reusable orchestration entry-point for CLIs and builders.
resolveDartSdkPath — robust Dart SDK location for AOT-compiled tools (where executable-relative SDK detection fails).
AnalyzerCacheGarbageCollector / AnalyzerCachePartition — opt-in reclamation of orphaned <analyzer-major>/<dart-sdk-version> cache partitions left behind by retired toolchains.

See the package README for motivation and examples.

Classes

AnalyzerCacheGarbageCollector: Opt-in garbage collector for orphaned analyzer-cache partitions.
AnalyzerCachePartition: One <analyzer-major>/<dart-sdk-version> 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.
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.

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

analyzerMajorVersion → const int: The major version of the analyzer package this build of tom_analyzer_shared was compiled against.

currentDartSdkVersion() → String: The <major>.<minor>.<patch> Dart SDK version of the running toolchain.
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.

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).