feat: recursively discover packages in nested workspaces (#968)

## Description

This PR adds support for recursively discovering packages in nested
workspaces, fixing the issue where `fvm dart pub workspace list` and
`fvm dart run melos list` produce inconsistent results.

## Problem

Currently, when a workspace root directory itself contains a
`workspace:` configuration in its `pubspec.yaml`, melos does not
recursively discover the packages listed in that nested workspace. This
causes `fvm dart run melos list` to have different results compared to
`fvm dart pub workspace list`.

### Example

In a monorepo structure like:
```
packages/
  base/
    ui/                        # workspace root with workspace: ['core', 'components']
      pubspec.yaml             # defines workspace: ['core', 'components']
      core/                    # package
        pubspec.yaml
      components/              # package
        pubspec.yaml
      example/                 # nested workspace with example
        pubspec.yaml           # defines workspace: ['example']
        example/               # example package
          pubspec.yaml
```

**Current behavior:**
- `fvm dart pub workspace list` discovers all packages including nested
ones: `ui`, `core`, `components`, `example`
- `fvm dart run melos list` only discovers the workspace root:
`packages/base/ui`

This inconsistency makes it difficult to manage packages in monorepos
with nested workspace structures.

## Solution

- Modified `_resolvePubspecFiles` to detect and recurse into nested
workspaces
- Added `_isWorkspacePubspec` helper to check if a pubspec.yaml defines
a workspace
- Added `_discoverNestedWorkspacePackages` to recursively discover
packages in nested workspaces
- Added comprehensive test cases covering various nested workspace
scenarios

The implementation now matches `dart pub workspace list` behavior by
recursively discovering all packages in nested workspaces.

## Changes

- `packages/melos/lib/src/package.dart`: Added recursive workspace
discovery logic (353 lines added)
- `packages/melos/test/package_test.dart`: Added 5 new test cases for
nested workspace discovery

## Testing

All existing tests pass, and 5 new test cases have been added:
- ✅ Basic nested workspace discovery
- ✅ Deeply nested workspaces (multiple levels)
- ✅ Nested workspaces with example packages  
- ✅ Ignore patterns for nested packages
- ✅ Complex nested workspace structures

## Verification

After this fix, `fvm dart run melos list` and `fvm dart pub workspace
list` will produce consistent results for nested workspace structures.

## Related

Fixes the inconsistency between `melos list` and `dart pub workspace
list` commands when dealing with nested workspaces.

## Type of Change

- [x] ✨ `feat` -- New feature (non-breaking change which adds
functionality)
- [ ] 🛠️ `fix` -- Bug fix (non-breaking change which fixes an issue)
- [x] ❌ `!` -- Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] 🧹 `refactor` -- Code refactor
- [ ] ✅ `ci` -- Build configuration change
- [ ] 📝 `docs` -- Documentation
- [ ] 🗑️ `chore` -- Chore

Author: MeandNi

docs/configuration/overview.mdx

@@ -98,6 +98,49 @@ This allows you to leverage Melos features like `melos version`,
 configuration for monorepos, this option provides flexibility for existing
 project structures and enables single package usage.
 
+## discoverNestedWorkspaces
+
+Whether to recursively discover packages in nested workspaces.
+
+When enabled, Melos will, in addition to the packages matched by your
+`workspace` globs, recursively discover packages inside any workspace roots
+(`pubspec.yaml` files that define a `workspace:` field) that are found under
+those globs. This makes the behaviour of `melos list` consistent with
+`dart pub workspace list` for nested workspace structures.
+
+Defaults to `false` to preserve the existing, non-recursive behaviour.
+
+```yaml
+melos:
+  discoverNestedWorkspaces: true
+  # Example workspace layout:
+  # packages/
+  #   base/
+  #     ui/                        # workspace root with workspace: ['core', 'components']
+  #       pubspec.yaml             # defines workspace: ['core', 'components']
+  #       core/
+  #         pubspec.yaml
+  #       components/
+  #         pubspec.yaml
+  #       example/                 # nested workspace with example
+  #         pubspec.yaml           # defines workspace: ['example']
+  #         example/
+  #           pubspec.yaml
+
+workspace:
+  - packages/**        # discovers ui, core, components, example, etc.
+```
+
+**Use cases:**
+- Monorepos that already use `dart pub workspace` with nested workspaces and
+  want `melos list`/`melos run` to see the same set of packages.
+- Projects where an intermediate package acts as a workspace root and contains
+  additional packages or examples underneath it.
+
+If you prefer the previous behaviour where only the packages directly matched
+by `workspace` globs are discovered, leave `discoverNestedWorkspaces` at its
+default value `false`.
+
 ## ignore
 
 A list of paths to local packages that are excluded from the Melos workspace.

melos.yaml.schema.json

@@ -62,6 +62,11 @@
       "description": "Whether to include the repository root as a package in the workspace. Defaults to false.",
       "default": false
     },
+    "discoverNestedWorkspaces": {
+      "type": "boolean",
+      "description": "Whether to recursively discover packages in nested workspaces. Defaults to false.",
+      "default": false
+    },
     "categories": {
       "type": "object",
       "description": "Categorize packages in the workspace.",

packages/melos/lib/src/command_runner/publish.dart

@@ -38,7 +38,7 @@ class PublishCommand extends MelosCommand {
   Future<void> run() async {
     final dryRun = argResults![publishOptionDryRun] as bool;
     final gitTagVersion = argResults![publishOptionGitTagVersion] as bool;
-    final yes = argResults![publishOptionYes] as bool || false;
+    final yes = argResults![publishOptionYes] as bool;
 
     final melos = Melos(logger: logger, config: config);
     final packageFilters = parsePackageFilters(config.path);

packages/melos/lib/src/package.dart

@@ -534,6 +534,7 @@ class PackageMap {
     required List<Glob> ignore,
     required Map<String, List<Glob>> categories,
     required MelosLogger logger,
+    bool discoverNestedWorkspaces = false,
   }) async {
     final pubspecFiles = await _resolvePubspecFiles(
       workspacePath: workspacePath,
@@ -543,6 +544,7 @@ class PackageMap {
         for (final pattern in _commonIgnorePatterns)
           createGlob(pattern, currentDirectoryPath: workspacePath),
       ],
+      discoverNestedWorkspaces: discoverNestedWorkspaces,
     );
 
     final packageMap = <String, Package>{};
@@ -621,6 +623,7 @@ The packages that caused the problem are:
     required String workspacePath,
     required List<Glob> packages,
     required List<Glob> ignore,
+    required bool discoverNestedWorkspaces,
   }) async {
     final pubspecEntities = await Stream.fromIterable(packages)
         .map(_createPubspecGlob)
@@ -637,7 +640,120 @@ The packages that caused the problem are:
         .map((file) => p.canonicalize(file.absolute.path))
         .toSet();
 
-    return paths.map(File.new).toList();
+    if (!discoverNestedWorkspaces) {
+      return paths.map(File.new).toList();
+    }
+
+    // Recursively discover packages in nested workspaces
+    final allPaths = <String>{...paths};
+    final nestedWorkspacePaths = <String>{};
+
+    // First pass: identify nested workspaces
+    for (final path in paths) {
+      final pubspecFile = File(path);
+      if (await _isWorkspacePubspec(pubspecFile)) {
+        nestedWorkspacePaths.add(p.dirname(path));
+      }
+    }
+
+    // Second pass: discover packages in nested workspaces
+    for (final nestedWorkspacePath in nestedWorkspacePaths) {
+      final nestedPubspecs = await _discoverNestedWorkspacePackages(
+        nestedWorkspacePath: nestedWorkspacePath,
+        rootWorkspacePath: workspacePath,
+        ignore: ignore,
+      );
+      allPaths.addAll(
+        nestedPubspecs.map((file) => p.canonicalize(file.absolute.path)),
+      );
+    }
+
+    return allPaths.map(File.new).toList();
+  }
+
+  /// Checks if a pubspec.yaml file defines a workspace.
+  static Future<bool> _isWorkspacePubspec(File pubspecFile) async {
+    try {
+      if (!pubspecFile.existsSync()) {
+        return false;
+      }
+      final content = await pubspecFile.readAsString();
+      final pubspec = Pubspec.parse(content);
+      return pubspec.workspace != null && pubspec.workspace!.isNotEmpty;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  /// Discovers all packages in a nested workspace.
+  static Future<List<File>> _discoverNestedWorkspacePackages({
+    required String nestedWorkspacePath,
+    required String rootWorkspacePath,
+    required List<Glob> ignore,
+  }) async {
+    final nestedPubspecFile = File(p.join(nestedWorkspacePath, 'pubspec.yaml'));
+    if (!await _isWorkspacePubspec(nestedPubspecFile)) {
+      return [];
+    }
+
+    final pubspec = Pubspec.parse(await nestedPubspecFile.readAsString());
+    final workspacePaths = pubspec.workspace ?? [];
+
+    final nestedPackages = <File>[];
+    final pubspecIgnoreGlobs = ignore.map(_createPubspecGlob).toList();
+    bool isIgnored(File file) =>
+        pubspecIgnoreGlobs.any((glob) => glob.matches(file.path));
+
+    // Convert relative workspace paths to absolute paths
+    for (final workspacePath in workspacePaths) {
+      final absoluteWorkspacePath = p.isAbsolute(workspacePath)
+          ? workspacePath
+          : p.join(nestedWorkspacePath, workspacePath);
+
+      // Look for pubspec.yaml files in the workspace path and subdirectories
+      final workspaceDir = Directory(absoluteWorkspacePath);
+      if (workspaceDir.existsSync()) {
+        // Check if the workspace path itself has a pubspec.yaml
+        final pubspecAtPath = File(
+          p.join(absoluteWorkspacePath, 'pubspec.yaml'),
+        );
+        if (pubspecAtPath.existsSync() && !isIgnored(pubspecAtPath)) {
+          nestedPackages.add(pubspecAtPath);
+        }
+
+        // Recursively search for pubspec.yaml files in subdirectories
+        await for (final entity in workspaceDir.list(recursive: true)) {
+          if (entity is File &&
+              p.basename(entity.path) == 'pubspec.yaml' &&
+              !isIgnored(entity)) {
+            final canonicalPath = p.canonicalize(entity.absolute.path);
+            // Skip the nested workspace root pubspec.yaml itself
+            final nestedPubspecCanonical = p.canonicalize(
+              nestedPubspecFile.absolute.path,
+            );
+            if (canonicalPath != nestedPubspecCanonical) {
+              nestedPackages.add(entity);
+            }
+          }
+        }
+      }
+    }
+
+    // Recursively discover packages in any nested workspaces we found
+    final allNestedPackages = <File>[...nestedPackages];
+    for (final packageFile in nestedPackages) {
+      if (await _isWorkspacePubspec(packageFile)) {
+        final nestedPath = p.dirname(packageFile.path);
+        final deeperNested = await _discoverNestedWorkspacePackages(
+          nestedWorkspacePath: nestedPath,
+          rootWorkspacePath: rootWorkspacePath,
+          ignore: ignore,
+        );
+        allNestedPackages.addAll(deeperNested);
+      }
+    }
+
+    return allNestedPackages;
   }
 
   static Glob _createPubspecGlob(Glob event) {

packages/melos/lib/src/workspace.dart

@@ -54,6 +54,7 @@ class MelosWorkspace {
       ignore: workspaceConfig.ignore,
       categories: workspaceConfig.categories,
       logger: logger,
+      discoverNestedWorkspaces: workspaceConfig.discoverNestedWorkspaces,
     );
     final dependencyOverridePackages = await PackageMap.resolvePackages(
       workspacePath: workspaceConfig.path,

packages/melos/lib/src/workspace_config.dart

@@ -241,6 +241,7 @@ class MelosWorkspaceConfig {
     this.ide = IDEConfigs.empty,
     this.commands = CommandConfigs.empty,
     this.useRootAsPackage = false,
+    this.discoverNestedWorkspaces = false,
   }) {
     _validate();
   }
@@ -375,6 +376,13 @@ class MelosWorkspaceConfig {
         ) ??
         false;
 
+    final discoverNestedWorkspaces =
+        assertKeyIsA<bool?>(
+          key: 'discoverNestedWorkspaces',
+          map: melosYaml,
+        ) ??
+        false;
+
     return MelosWorkspaceConfig(
       path: path,
       name: name,
@@ -404,6 +412,7 @@ class MelosWorkspaceConfig {
               repositoryIsConfigured: repository != null,
             ),
       useRootAsPackage: useRootAsPackage,
+      discoverNestedWorkspaces: discoverNestedWorkspaces,
     );
   }
 
@@ -414,19 +423,22 @@ class MelosWorkspaceConfig {
         path: Directory.current.path,
         commands: CommandConfigs.empty,
         useRootAsPackage: false,
+        discoverNestedWorkspaces: false,
       );
 
   @visibleForTesting
   MelosWorkspaceConfig.emptyWith({
     String? name,
     String? path,
     bool? useRootAsPackage,
+    bool? discoverNestedWorkspaces,
   }) : this(
          name: name ?? 'Melos',
          packages: [],
          path: path ?? Directory.current.path,
          commands: CommandConfigs.empty,
          useRootAsPackage: useRootAsPackage ?? false,
+         discoverNestedWorkspaces: discoverNestedWorkspaces ?? false,
        );
 
   /// Loads the [MelosWorkspaceConfig] for the workspace at [workspaceRoot].
@@ -579,6 +591,10 @@ class MelosWorkspaceConfig {
   /// Defaults to false.
   final bool useRootAsPackage;
 
+  /// Whether to recursively discover packages in nested workspaces.
+  /// Defaults to false.
+  final bool discoverNestedWorkspaces;
+
   /// Validates this workspace configuration for consistency.
   void _validate() {
     final workspaceDir = Directory(path);
@@ -615,6 +631,7 @@ class MelosWorkspaceConfig {
       other.repository == repository &&
       other.sdkPath == sdkPath &&
       other.useRootAsPackage == useRootAsPackage &&
+      other.discoverNestedWorkspaces == discoverNestedWorkspaces &&
       const DeepCollectionEquality(
         GlobEquality(),
       ).equals(other.packages, packages) &&
@@ -633,6 +650,7 @@ class MelosWorkspaceConfig {
       repository.hashCode ^
       sdkPath.hashCode ^
       useRootAsPackage.hashCode ^
+      discoverNestedWorkspaces.hashCode ^
       const DeepCollectionEquality(GlobEquality()).hash(packages) &
           const DeepCollectionEquality(GlobEquality()).hash(ignore) ^
       scripts.hashCode ^
@@ -645,6 +663,8 @@ class MelosWorkspaceConfig {
         if (repository != null) 'repository': repository!,
         if (sdkPath != null) 'sdkPath': sdkPath!,
         if (useRootAsPackage) 'useRootAsPackage': useRootAsPackage,
+        if (discoverNestedWorkspaces)
+          'discoverNestedWorkspaces': discoverNestedWorkspaces,
         'categories': categories.map((category, packages) {
           return MapEntry(
             category,