Explain why specific packages are included in `pub deps [<package>...]` (#4945)
diff --git a/lib/src/command/deps.dart b/lib/src/command/deps.dart index 8304b22..7d3a50b 100644 --- a/lib/src/command/deps.dart +++ b/lib/src/command/deps.dart
@@ -27,13 +27,13 @@ String get description => 'Print package dependencies.'; @override - String get argumentsDescription => '[arguments...]'; + String get argumentsDescription => '[<package>...]'; @override String get docUrl => 'https://dart.dev/tools/pub/cmd/pub-deps'; @override - bool get takesArguments => false; + bool get takesArguments => true; /// Whether to include dev dependencies. bool get _includeDev => argResults.flag('dev'); @@ -65,6 +65,14 @@ help: 'Output dependency information in a json format.', ); + argParser.addFlag( + 'from-root', + negatable: false, + help: + 'Show paths from root packages down to the target packages ' + 'instead of inverted.', + ); + argParser.addOption( 'directory', abbr: 'C', @@ -76,6 +84,30 @@ @override Future<void> runProtected() async { final buffer = StringBuffer(); + final targetPackages = argResults.rest; + + if (targetPackages.isNotEmpty) { + if (argResults.flag('json')) { + usageException('Cannot combine --json and package arguments.'); + } + if (argResults.flag('executables')) { + usageException('Cannot combine --executables and package arguments.'); + } + if (argResults.wasParsed('style') && + argResults.option('style') != 'tree') { + usageException( + 'Cannot combine --style=${argResults.option('style')} and ' + 'package arguments.', + ); + } + await _outputTargetPackages(buffer, targetPackages); + log.message(buffer.toString()); + return; + } + + if (argResults.flag('from-root')) { + usageException('Cannot specify --from-root without target packages.'); + } if (argResults.flag('json')) { if (argResults.wasParsed('dev')) { @@ -393,6 +425,251 @@ String _labelPackage(Package package) => '${log.bold(package.name)} ${package.version}'; + /// Outputs dependency paths explaining why [targets] are included. + Future<void> _outputTargetPackages( + StringBuffer buffer, + List<String> targets, + ) async { + final graph = await entrypoint.packageGraph; + final workspacePackageNames = { + for (final p in entrypoint.workspaceRoot.transitiveWorkspace) p.name, + }; + final reachableNames = { + ...workspacePackageNames, + ...await _getAllDependencies(), + }; + + for (final target in targets) { + if (!graph.packages.containsKey(target)) { + dataError('Package "$target" is not a dependency.'); + } + if (!reachableNames.contains(target)) { + dataError( + 'Package "$target" is only included via dev_dependencies. ' + 'Run without --no-dev to see paths.', + ); + } + } + + for (final sdk in sdks.values) { + if (!sdk.isAvailable) continue; + buffer.writeln("${log.bold('${sdk.name} SDK')} ${sdk.version}"); + } + + if (argResults.flag('from-root')) { + await _outputFromRootTree( + buffer, + targets, + workspacePackageNames, + reachableNames, + ); + } else { + await _outputInvertedTree( + buffer, + targets, + workspacePackageNames, + reachableNames, + ); + } + } + + /// Generates an inverted dependency tree starting from each package in + /// [targets] and walking up to the workspace root packages. + Future<void> _outputInvertedTree( + StringBuffer buffer, + List<String> targets, + Set<String> workspacePackageNames, + Set<String> reachableNames, + ) async { + final graph = await entrypoint.packageGraph; + + List<Package> dependeesOf(String targetName, {required bool isTargetRoot}) { + if (!isTargetRoot && workspacePackageNames.contains(targetName)) { + return const []; + } + final result = <Package>[]; + for (final name in reachableNames) { + if (name == targetName) continue; + final package = graph.packages[name]!; + if (_childrenOf(package, workspacePackageNames).contains(targetName)) { + result.add(package); + } + } + result.sort((a, b) => a.name.compareTo(b.name)); + return result; + } + + final packageTree = <String, Map>{}; + for (final targetName in targets) { + final targetPackage = await _getPackage(targetName); + final rootMap = <String, Map>{}; + packageTree[_labelPackage(targetPackage)] = rootMap; + + final toWalk = Queue<(Package, String, Map<String, Map>)>(); + final visited = <String>{targetPackage.name}; + + for (final dependee in dependeesOf( + targetPackage.name, + isTargetRoot: true, + )) { + toWalk.add((dependee, targetPackage.name, rootMap)); + } + + while (toWalk.isNotEmpty) { + final (package, dependedOn, map) = toWalk.removeFirst(); + final annotation = _edgeAnnotation( + package, + dependedOn, + workspacePackageNames, + ); + final nextDependees = dependeesOf(package.name, isTargetRoot: false); + + if (nextDependees.isNotEmpty && !visited.add(package.name)) { + map['${log.gray('${package.name}...')} $annotation'] = + <String, Map>{}; + continue; + } + + final childMap = <String, Map>{}; + map['${_labelPackage(package)} $annotation'] = childMap; + for (final dependee in nextDependees) { + toWalk.add((dependee, package.name, childMap)); + } + } + } + + buffer.write(tree.fromMap(packageTree)); + } + + /// Generates a top-down dependency tree from workspace roots pruned to paths + /// that reach [targets]. + Future<void> _outputFromRootTree( + StringBuffer buffer, + List<String> targets, + Set<String> workspacePackageNames, + Set<String> reachableNames, + ) async { + final graph = await entrypoint.packageGraph; + final targetSet = targets.toSet(); + + Set<String> ancestorsOfTarget(String target) { + final ancestors = <String>{target}; + final queue = Queue<String>()..add(target); + while (queue.isNotEmpty) { + final current = queue.removeFirst(); + final isCurrentRoot = workspacePackageNames.contains(current); + for (final name in reachableNames) { + if (name == target) continue; + if (isCurrentRoot && !workspacePackageNames.contains(name)) { + continue; + } + final package = graph.packages[name]!; + if (_childrenOf(package, workspacePackageNames).contains(current)) { + if (ancestors.add(name)) { + queue.add(name); + } + } + } + } + return ancestors; + } + + final ancestorsByTarget = { + for (final target in targetSet) target: ancestorsOfTarget(target), + }; + + List<String> prunedChildrenOf(Package package) { + final result = <String>[]; + for (final dep in _childrenOf(package, workspacePackageNames)) { + if (!reachableNames.contains(dep)) continue; + final reachesSomeTarget = targetSet.any( + (target) => + package.name != target && + ancestorsByTarget[target]!.contains(dep), + ); + if (reachesSomeTarget) { + result.add(dep); + } + } + return result; + } + + final packageTree = <String, Map>{}; + final toWalk = Queue<(Package, String?, Map<String, Map>)>(); + final visited = <String>{}; + + for (final name in workspacePackageNames) { + final reachesOrIsTarget = targetSet.any( + (target) => ancestorsByTarget[target]!.contains(name), + ); + if (!reachesOrIsTarget) continue; + toWalk.add((await _getPackage(name), null, packageTree)); + } + + while (toWalk.isNotEmpty) { + final (package, parentName, map) = toWalk.removeFirst(); + final annotation = + parentName == null + ? null + : _edgeAnnotation( + graph.packages[parentName]!, + package.name, + workspacePackageNames, + ); + final labelSuffix = annotation == null ? '' : ' $annotation'; + final children = prunedChildrenOf(package); + + if (children.isNotEmpty && !visited.add(package.name)) { + map['${log.gray('${package.name}...')}$labelSuffix'] = <String, Map>{}; + continue; + } + + final childMap = <String, Map>{}; + map['${_labelPackage(package)}$labelSuffix'] = childMap; + for (final dep in children) { + toWalk.add((await _getPackage(dep), package.name, childMap)); + } + } + + buffer.write(tree.fromMap(packageTree)); + } + + Iterable<String> _childrenOf( + Package package, + Set<String> workspacePackageNames, + ) { + if (!workspacePackageNames.contains(package.name)) { + return package.dependencies.keys; + } + return { + ...package.dependencies.keys, + if (_includeDev) ...package.devDependencies.keys, + ...package.pubspec.dependencyOverrides.keys, + }; + } + + String _edgeAnnotation( + Package parent, + String childName, + Set<String> workspacePackageNames, + ) { + if (!workspacePackageNames.contains(parent.name)) { + final dep = parent.dependencies[childName]!; + return log.gray('(${dep.constraint})'); + } + final dep = parent.dependencies[childName]; + final devDep = _includeDev ? parent.devDependencies[childName] : null; + final overrideDep = parent.pubspec.dependencyOverrides[childName]; + final parts = <String>[ + if (dep != null) + '${dep.constraint}' + else if (devDep != null) + '${devDep.constraint}, dev', + if (overrideDep != null) 'override: ${overrideDep.constraint}', + ]; + return log.gray('(${parts.join(', ')})'); + } + /// Gets the names of the non-immediate dependencies of the workspace /// packages. Future<Set<String>> _getTransitiveDependencies() async {
diff --git a/test/deps_test.dart b/test/deps_test.dart index 11dc020..12cf300 100644 --- a/test/deps_test.dart +++ b/test/deps_test.dart
@@ -447,4 +447,188 @@ ); }); }); + + group('explains why specific packages are included', () { + test('in inverted tree form by default', () async { + await pubGet(); + await runPub( + args: ['deps', 'shared'], + output: ''' + Dart SDK 3.1.2+3 + shared 1.2.3 + ├── transitive 1.2.3 (any) + │ └── normal 1.2.3 (any) + │ └── myapp 0.0.0 (any) + └── unittest 1.2.3 (any) + └── myapp 0.0.0 (any, dev) + ''', + ); + }); + + test('in inverted tree form with --no-dev', () async { + await pubGet(); + await runPub( + args: ['deps', 'shared', '--no-dev'], + output: ''' + Dart SDK 3.1.2+3 + shared 1.2.3 + └── transitive 1.2.3 (any) + └── normal 1.2.3 (any) + └── myapp 0.0.0 (any) + ''', + ); + }); + + test( + 'in inverted tree form for overridden and circular packages', + () async { + await pubGet(); + await runPub( + args: ['deps', 'overridden', 'override_only', 'circular_a'], + output: ''' + Dart SDK 3.1.2+3 + circular_a 1.2.3 + ├── circular_b 1.2.3 (any) + │ └── circular_a... (any) + └── normal 1.2.3 (any) + └── myapp 0.0.0 (any) + overridden 2.0.0 + └── myapp 0.0.0 (1.0.0, override: 2.0.0) + override_only 1.2.3 + └── myapp 0.0.0 (override: any) + ''', + ); + }, + ); + + test('in top-down tree form with --from-root', () async { + await pubGet(); + await runPub( + args: ['deps', 'shared', '--from-root'], + output: ''' + Dart SDK 3.1.2+3 + myapp 0.0.0 + ├── normal 1.2.3 (any) + │ └── transitive 1.2.3 (any) + │ └── shared 1.2.3 (any) + └── unittest 1.2.3 (any, dev) + └── shared 1.2.3 (any) + ''', + ); + }); + + test('in top-down tree form with --from-root and --no-dev', () async { + await pubGet(); + await runPub( + args: ['deps', 'shared', '--from-root', '--no-dev'], + output: ''' + Dart SDK 3.1.2+3 + myapp 0.0.0 + └── normal 1.2.3 (any) + └── transitive 1.2.3 (any) + └── shared 1.2.3 (any) + ''', + ); + }); + + test('errors when package is not a dependency', () async { + await pubGet(); + await runPub( + args: ['deps', 'nonexistent'], + error: 'Package "nonexistent" is not a dependency.', + exitCode: 65, + ); + }); + + test( + 'errors when package is only a dev dependency with --no-dev', + () async { + await pubGet(); + await runPub( + args: ['deps', 'dev_only', '--no-dev'], + error: + 'Package "dev_only" is only included via dev_dependencies. ' + 'Run without --no-dev to see paths.', + exitCode: 65, + ); + }, + ); + + test('rejects incompatible flags', () async { + await pubGet(); + await runPub( + args: ['deps', '--from-root'], + error: contains('Cannot specify --from-root without target packages.'), + exitCode: 64, + ); + await runPub( + args: ['deps', 'shared', '--json'], + error: contains('Cannot combine --json and package arguments.'), + exitCode: 64, + ); + await runPub( + args: ['deps', 'shared', '--executables'], + error: contains('Cannot combine --executables and package arguments.'), + exitCode: 64, + ); + await runPub( + args: ['deps', 'shared', '--style=compact'], + error: contains( + 'Cannot combine --style=compact and package arguments.', + ), + exitCode: 64, + ); + }); + + test('works across workspace packages', () async { + await d.dir(appPath, [ + d.libPubspec( + 'myapp', + '0.0.0', + deps: {'normal': '^1.0.0'}, + extras: { + 'workspace': ['pkgs/sub_a'], + }, + sdk: '^3.5.0', + ), + d.dir('pkgs', [ + d.dir('sub_a', [ + d.libPubspec( + 'sub_a', + '1.0.0', + deps: {'shared': '^1.0.0'}, + resolutionWorkspace: true, + ), + ]), + ]), + ]).create(); + + await pubGet(environment: {'_PUB_TEST_SDK_VERSION': '3.5.0'}); + await runPub( + args: ['deps', 'shared'], + environment: {'_PUB_TEST_SDK_VERSION': '3.5.0'}, + output: ''' + Dart SDK 3.5.0 + shared 1.2.3 + ├── sub_a 1.0.0 (^1.0.0) + └── transitive 1.2.3 (any) + └── normal 1.2.3 (any) + └── myapp 0.0.0 (^1.0.0) + ''', + ); + await runPub( + args: ['deps', 'shared', '--from-root'], + environment: {'_PUB_TEST_SDK_VERSION': '3.5.0'}, + output: ''' + Dart SDK 3.5.0 + myapp 0.0.0 + └── normal 1.2.3 (^1.0.0) + └── transitive 1.2.3 (any) + └── shared 1.2.3 (any) + sub_a 1.0.0 + └── shared 1.2.3 (^1.0.0) + ''', + ); + }); + }); }
diff --git a/test/testdata/goldens/help_test/pub deps --help.txt b/test/testdata/goldens/help_test/pub deps --help.txt index 3e8e27e..2f81495 100644 --- a/test/testdata/goldens/help_test/pub deps --help.txt +++ b/test/testdata/goldens/help_test/pub deps --help.txt
@@ -4,7 +4,7 @@ $ pub deps --help Print package dependencies. -Usage: pub deps [arguments...] +Usage: pub deps [<package>...] -h, --help Print this usage information. -s, --style How output should be displayed. [compact, tree (default), list] @@ -12,6 +12,7 @@ (defaults to on) --executables List all available executables. --json Output dependency information in a json format. + --from-root Show paths from root packages down to the target packages instead of inverted. -C, --directory=<dir> Run this in the directory <dir>. Run "pub help" to see global options.