homebrew: Add info about changed packages (#31)

homebrew now returns details about changed and unchanged packages
after performing the operations.

Fixes: ansible/ansible#59376

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

changelogs/fragments/59376-homebrew_fix.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- Add information about changed packages in homebrew returned facts (https://github.com/ansible/ansible/issues/59376).

plugins/modules/packaging/os/homebrew.py

@@ -78,6 +78,7 @@ notes:
   - When used with a `loop:` each package will be processed individually,
     it is much more efficient to pass the list directly to the `name` option.
 '''
+
 EXAMPLES = '''
 # Install formula foo with 'brew' in default path (C(/usr/local/bin))
 - homebrew:
@@ -135,6 +136,28 @@ EXAMPLES = '''
     upgrade_options: ignored-pinned
 '''
 
+RETURN = '''
+msg:
+    description: if the cache was updated or not
+    returned: always
+    type: str
+    sample: "Changed: 0, Unchanged: 2"
+unchanged_pkgs:
+    description:
+    - List of package names which are unchanged after module run
+    - "Added in version 2.10"
+    returned: success
+    type: list
+    sample: ["awscli", "ag"]
+changed_pkgs:
+    description:
+    - List of package names which are changed after module run
+    - "Added in version 2.10"
+    returned: success
+    type: list
+    sample: ['git', 'git-cola']
+'''
+
 import os.path
 import re
 
@@ -389,6 +412,8 @@ class Homebrew(object):
         self.changed = False
         self.changed_count = 0
         self.unchanged_count = 0
+        self.changed_pkgs = []
+        self.unchanged_pkgs = []
         self.message = ''
 
     def _setup_instance_vars(self, **kwargs):
@@ -519,6 +544,7 @@ class Homebrew(object):
             self.changed = True
             self.message = 'Homebrew would be updated.'
             raise HomebrewException(self.message)
+
         rc, out, err = self.module.run_command([
             self.brew_path,
             'update',
@@ -576,6 +602,7 @@ class Homebrew(object):
 
         if self._current_package_is_installed():
             self.unchanged_count += 1
+            self.unchanged_pkgs.append(self.current_package)
             self.message = 'Package already installed: {0}'.format(
                 self.current_package,
             )
@@ -603,6 +630,7 @@ class Homebrew(object):
 
         if self._current_package_is_installed():
             self.changed_count += 1
+            self.changed_pkgs.append(self.current_package)
             self.changed = True
             self.message = 'Package installed: {0}'.format(self.current_package)
             return True
@@ -636,6 +664,7 @@ class Homebrew(object):
                 self.current_package,
             )
             self.unchanged_count += 1
+            self.unchanged_pkgs.append(self.current_package)
             return True
 
         if self.module.check_mode:
@@ -655,6 +684,7 @@ class Homebrew(object):
 
         if self._current_package_is_installed() and not self._current_package_is_outdated():
             self.changed_count += 1
+            self.changed_pkgs.append(self.current_package)
             self.changed = True
             self.message = 'Package upgraded: {0}'.format(self.current_package)
             return True
@@ -699,6 +729,7 @@ class Homebrew(object):
 
         if not self._current_package_is_installed():
             self.unchanged_count += 1
+            self.unchanged_pkgs.append(self.current_package)
             self.message = 'Package already uninstalled: {0}'.format(
                 self.current_package,
             )
@@ -721,6 +752,7 @@ class Homebrew(object):
 
         if not self._current_package_is_installed():
             self.changed_count += 1
+            self.changed_pkgs.append(self.current_package)
             self.changed = True
             self.message = 'Package uninstalled: {0}'.format(self.current_package)
             return True
@@ -766,6 +798,7 @@ class Homebrew(object):
 
         if rc == 0:
             self.changed_count += 1
+            self.changed_pkgs.append(self.current_package)
             self.changed = True
             self.message = 'Package linked: {0}'.format(self.current_package)
 
@@ -812,6 +845,7 @@ class Homebrew(object):
 
         if rc == 0:
             self.changed_count += 1
+            self.changed_pkgs.append(self.current_package)
             self.changed = True
             self.message = 'Package unlinked: {0}'.format(self.current_package)
 
@@ -920,10 +954,17 @@ def main():
                     upgrade_all=upgrade_all, install_options=install_options,
                     upgrade_options=upgrade_options)
     (failed, changed, message) = brew.run()
+    changed_pkgs = brew.changed_pkgs
+    unchanged_pkgs = brew.unchanged_pkgs
+
     if failed:
         module.fail_json(msg=message)
-    else:
+    module.exit_json(
-        module.exit_json(changed=changed, msg=message)
+        changed=changed,
+        msg=message,
+        unchanged_pkgs=unchanged_pkgs,
+        changed_pkgs=changed_pkgs
+    )
 
 
 if __name__ == '__main__':