fix: stash uncommitted changes instead of aborting during ref checkout

Author: flxapps

lib/doc_generator/doc_generator.dart

@@ -29,11 +29,13 @@ Future<PackageApi> generateDocs({
     exit(1);
   }
 
-  // Check for uncommitted changes if we're going to checkout a ref
+  // Stash uncommitted changes if we're going to checkout a different ref.
+  // This allows the tool to work in CI environments where prior steps
+  // (e.g. `flutter pub get`) create uncommitted artefacts.
+  bool didStash = false;
   if (gitRef != 'HEAD' && GitUtils.hasUncommittedChanges(gitRoot.path)) {
-    logger.err('Repository has uncommitted changes. Please commit or stash them before proceeding.');
-    logger.err('This prevents potential data loss during ref checkout.');
-    exit(1);
+    logger.info('Stashing uncommitted changes before checking out ref...');
+    didStash = await GitUtils.stashChanges(gitRoot.path);
   }
 
   final originalRef = await GitUtils.getCurrentRef(gitRoot.path);
@@ -60,6 +62,10 @@ Future<PackageApi> generateDocs({
       } else {
         await GitUtils.checkoutRef(originalRef, gitRoot.path);
       }
+      if (didStash) {
+        logger.info('Restoring stashed changes...');
+        await GitUtils.popStash(gitRoot.path);
+      }
       logger.info('Successfully restored original state');
     } catch (e) {
       logger.err('Warning: Failed to restore original state: $e');
@@ -246,6 +252,6 @@ Future<PackageApi> generateDocs({
 
     return packageApi;
   } finally {
-    restoreOriginalState();
+    await restoreOriginalState();
   }
 }

lib/doc_generator/git_utils.dart

@@ -99,6 +99,43 @@ class GitUtils {
     }
   }
 
+  /// Stashes any uncommitted changes (including untracked files)
+  /// Returns true if changes were stashed, false if the working tree was clean.
+  static Future<bool> stashChanges(String? root) async {
+    try {
+      final result = await Process.run(
+        'git',
+        ['stash', 'push', '--include-untracked', '-m', 'mtrust_api_guard_auto_stash'],
+        workingDirectory: root,
+      );
+      if (result.exitCode != 0) {
+        throw GitException('Failed to stash changes: ${result.stderr}');
+      }
+      // "No local changes to save" means nothing was stashed
+      return !result.stdout.toString().contains('No local changes to save');
+    } on ProcessException catch (e) {
+      throw GitException('Git command not found: ${e.message}');
+    }
+  }
+
+  /// Pops the most recent stash entry.
+  /// Silently succeeds if there is nothing to pop.
+  static Future<void> popStash(String? root) async {
+    try {
+      final result = await Process.run(
+        'git',
+        ['stash', 'pop'],
+        workingDirectory: root,
+      );
+      if (result.exitCode != 0) {
+        // Log but don't throw – a pop failure shouldn't crash the tool
+        logger.err('Warning: Failed to pop stash: ${result.stderr}');
+      }
+    } on ProcessException catch (e) {
+      throw GitException('Git command not found: ${e.message}');
+    }
+  }
+
   /// Checks out a specific git ref
   /// Throws [GitException] if the operation fails
   static Future<void> checkoutRef(String ref, String? root) async {