homebrew: Add force_formula parameter to pass --formula to brew command (#8275)

* homebrew: Add force_formula parameter to pass --formula to brew command

Some formulas have names that are also cask formulas (e.g. docker).
When trying to install such a formula, brew prints a warning and returns
a non-zero exit code. This causes Ansible to halt and report the failure.
By allowing the task to set force_formula, we can sidestep this problem.

* Add changelog fragment

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/modules/homebrew.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

tests/integration/targets/docker/handlers/main.yml

@@ -0,0 +1,11 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: uninstall docker
+  community.general.homebrew:
+    name: docker
+    state: absent
+  become: true
+  become_user: "{{ brew_stat.stat.pw_name }}"

tests/integration/targets/docker/tasks/main.yml

@@ -0,0 +1,39 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- when: ansible_facts.distribution == 'MacOSX'
+  block:
+    - name: MACOS | Find brew binary
+      command: which brew
+      register: brew_which
+
+    - name: MACOS | Get owner of brew binary
+      stat:
+        path: "{{ brew_which.stdout }}"
+      register: brew_stat
+
+    - name: MACOS | Install docker without --formula
+      community.general.homebrew:
+        name: docker
+        state: present
+      become: true
+      become_user: "{{ brew_stat.stat.pw_name }}"
+      ignore_errors: true
+      register: result
+
+    - name: Check that installing docker without --formula raises warning
+      assert:
+        that:
+          - result is failed
+
+    - name: MACOS | Install docker
+      community.general.homebrew:
+        name: docker
+        state: present
+        force_formula: true
+      become: true
+      become_user: "{{ brew_stat.stat.pw_name }}"
+      notify:
+        - uninstall docker