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.