Add back replace-type (#898)

* Add back `replace-types`

Port the `replace-type` parameter into mockery v3. This changes the config schema used in the v2 replace-type parameter to be more grokable. This is also a practical matter: the somewhat complex parsing mechanism in v2 is replaced by simple struct attributes.

The implementation here is quite different from v2. The templating system in v3 requires type information for all types, and thus we cannot do simple string replacements. We have to call `packages.Load` on the referenced type so we can get real type information. This means that `replace-type` will incur additional latency. This latency penalty, however, grants us additional correctness of implementation: the mock templates will have full type information, and if something about the `replace-type` parameter is wrong (either package path or type name don't exist), mockery will explicitly log this as an error.

This does _not_ implement replacements of type constraints as done in v2: #750. This work still needs to be done.

Per #864

* Additional documentation

* Add docs and hint in log message on how to enable force-file-write.

Author: LandonTClipp

.github/workflows/documentation.yml

@@ -1,7 +1,7 @@
 name: documentation
 on:
   push:
-    branches: [ v3 ]
+    branches: [ master, v3 ]
 permissions:
   contents: write
 jobs:
@@ -28,4 +28,4 @@ jobs:
       - name: Deploy docs
         run: "mike deploy --push --update-aliases $(grep VERSION mockery-tools.env | cut -d'=' -f 2 | cut -d'.' -f1-2) v3"
         env:
-          GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
+          GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}

.github/workflows/reusable-testing.yml

@@ -27,7 +27,7 @@ jobs:
           go-version: ${{ matrix.go_vers }}
 
       - name: Download dependencies
-        run: go mod download
+        run: go mod download -x
 
       - name: Test
         run: go run github.com/go-task/task/v3/cmd/task test.ci

.github/workflows/tag-and-release.yml

@@ -6,12 +6,11 @@ on:
 permissions:
   contents: write
 jobs:
-  # TODO: temporarily disable testing during alpha development
-  #test:
-  #    uses: ./.github/workflows/reusable-testing.yml
+  test:
+      uses: ./.github/workflows/reusable-testing.yml
   tag:
     runs-on: ubuntu-latest
-    #needs: test
+    needs: test
     outputs:
       tag_result: ${{ steps.tag.outputs.tag_result }}
       requested_version: ${{ steps.tag.outputs.requested_version }}
@@ -96,4 +95,4 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GORELEASER_GITHUB_TOKEN }}
           HOMEBREW_TAP_TOKEN: ${{ secrets.GORELEASER_HOMEBREW_TAP_TOKEN }}
           GORELEASER_CURRENT_TAG: ${{ needs.tag.outputs.requested_version }}
-          #GORELEASER_PREVIOUS_TAG: ${{ needs.tag.outputs.previous_version }}
+          #GORELEASER_PREVIOUS_TAG: ${{ needs.tag.outputs.previous_version }}

.github/workflows/testing-dispatch.yml

@@ -12,4 +12,4 @@ jobs:
   test:
       uses: ./.github/workflows/reusable-testing.yml
       with:
-        ref: ${{ inputs.ref }}
+        ref: ${{ inputs.ref }}

.github/workflows/testing.yml

@@ -2,14 +2,8 @@ name: Go Test
 
 on:
   pull_request:
-    branches: [v3]
+    branches: [ master, v3 ]
 
 jobs:
   test:
-      runs-on: ubuntu-latest
-      steps:
-        - uses: actions/checkout@v2
-          with:
-            fetch-depth: 0
-        - uses: ./.github/workflows/reusable-testing.yml
-
+      uses: ./.github/workflows/reusable-testing.yml

.mockery.yml

@@ -10,6 +10,20 @@ template-data:
   boilerplate-file: "./.boilerplate.txt"
 packages:
   github.com/vektra/mockery/v3/internal/fixtures/buildtag/comment:
+  github.com/vektra/mockery/v3/internal/fixtures/example_project/replace_type:
+    config:
+      recursive: True
+    interfaces:
+      RType:
+        configs:
+        - {}
+        - mockname: RTypeReplaced1
+          replace-type:
+            github.com/vektra/mockery/v3/internal/fixtures/example_project/replace_type/rti/rt1:
+              RType1:
+                pkg-path: github.com/vektra/mockery/v3/internal/fixtures/example_project/replace_type/rti/rt2
+                type-name: RType2
+
   github.com/vektra/mockery/v3/internal/fixtures:
     interfaces:
       RequesterVariadic:

Taskfile.yml

@@ -12,7 +12,7 @@ tasks:
     sources:
       - "**/*.go"
     cmds:
-      - go fmt ./...
+      - gofumpt -l -w .
 
   mocks:
     desc: generate new mocks from scratch
@@ -83,11 +83,11 @@ tasks:
       - ./e2e/run_all.sh
 
   test.ci:
-    deps: [fmt, lint]
+    deps: [lint]
     cmds:
-      - task: mocks.remove
-      - task: mocks.generate
+      - task: mocks
       - task: test
+      - task: mocks.remove
       - task: test.e2e
 
   default:

docs/configuration.md

@@ -57,6 +57,7 @@ Parameter Descriptions
 | `exclude-subpkg-regex`                                 | :fontawesome-solid-x:     | `#!yaml []`                           | A list of regular expressions that denote which subpackages should be excluded when `#!yaml recursive: true` |
 | `exclude-regex`                                        | :fontawesome-solid-x:     | `#!yaml ""`                           | When set along with `include-regex`, then interfaces which match `include-regex` but also match `exclude-regex` will not be generated. If `all` is set, or if `include-regex` is not set, then `exclude-regex` has no effect.                        |
 | `filename`                                             | :fontawesome-solid-check: | `#!yaml "mock_{{.InterfaceName}}.go"` | The name of the file the mock will reside in.                                                                                                                                                                                                        |
+| `force-file-write`                                     | :fontawesome-solid-x:     | `#!yaml false`                        | When set to `#!yaml force-file-write: true`, mockery will forcibly overwrite any existing files. |
 | `formatter`                                            | :fontawesome-solid-x:     | `#!yaml "goimports"`                  | The formatter to use on the rendered template. Choices are: `gofmt`, `goimports`, `noop`.                                                                                                                                                            |
 | `include-regex`                                        | :fontawesome-solid-x:     | `#!yaml ""`                           | When set, only interface names that match the expression will be generated. This setting is ignored if `all: True` is specified in the configuration. To further refine the interfaces generated, use `exclude-regex`.                               |
 | `log-level`                                            | :fontawesome-solid-x:     | `#!yaml "info"`                       | Set the level of the logger                                                                                                                                                                                                                          |
@@ -65,11 +66,25 @@ Parameter Descriptions
 | [`packages`](features.md#packages-configuration)       | :fontawesome-solid-x:     | `#!yaml null`                         | A dictionary containing configuration describing the packages and interfaces to generate mocks for.                                                                                                                                                  |
 | `pkgname`                                              | :fontawesome-solid-check: | `#!yaml "{{.SrcPackageName}}"         | The `#!go package name` given to the generated mock files.                                                                                                                                                                                           |
 | [`recursive`](features.md#recursive-package-discovery) | :fontawesome-solid-x:     | `#!yaml false`                        | When set to `true` on a particular package, mockery will recursively search for all sub-packages and inject those packages into the config map.                                                                                                      |
+| [`replace-type`](replace-type.md)                      | :fontawesome-solid-x:     | `#!yaml {}`                           | Use this parameter to specify type replacements.                                 |
 | `tags`                                                 | :fontawesome-solid-x:     | `#!yaml ""`                           | A space-separated list of additional build tags to load packages.                                                                                                                                                                                    |
 | `template`                                             | :fontawesome-solid-x:     | `#!yaml ""`                           | The template to use. The choices are `moq`, `mockery`, or a file path provided by `file://path/to/file.txt`.                                                                                                                                         |
 | `template-data`                                        | :fontawesome-solid-x:     | `#!yaml {}`                           | A `map[string]any` that provides arbitrary options to the template. Each template will have a different set of accepted keys. Refer to each template's documentation for more details.                                                               |
 
 
+Config Templates
+----------------
+
+Parameters marked as being templated have access to a number of template variables and functions.
+
+### Variables
+
+The variables provided are specified in the [`ConfigData`](https://pkg.go.dev/github.com/vektra/mockery/v3/template#ConfigData) struct.
+
+### Functions
+
+All of the functions defined in [`StringManipulationFuncs`](https://pkg.go.dev/github.com/vektra/mockery/v3/template#pkg-variables) are available to templated parameters.
+
 Merging Precedence
 ------------------
 

docs/replace-type.md

@@ -0,0 +1,57 @@
+---
+title: replace-type
+---
+
+## Description
+
+The `#!yaml replace-type:` parameter allows you to replace a type in the generated mocks with another type. Take for example the following interface:
+
+
+```go title="interface.go"
+package replace_type
+
+import (
+    "github.com/vektra/mockery/v3/internal/fixtures/example_project/replace_type/rti/rt1"
+    "github.com/vektra/mockery/v3/internal/fixtures/example_project/replace_type/rti/rt2"
+)
+
+type RType interface {
+    Replace1(f rt1.RType1)
+}
+```
+
+You can selectively replace the `rt1.RType1` with a new type if so desired. For example:
+
+```yaml title=".mockery.yml"
+replace-type:
+  github.com/vektra/mockery/v3/internal/fixtures/example_project/replace_type/rti/rt1:
+    RType1:
+      pkg-path: github.com/vektra/mockery/v3/internal/fixtures/example_project/replace_type/rti/rt2
+      type-name: RType2
+```
+
+The mock will now replace all instances of `rt1.RType1` with `rt2.RType2`. You can see the before and after of `mockery`-style mocks:
+
+=== "before"
+
+    ```go
+    // Replace2 provides a mock function for the type RTypeReplaced1
+    func (_mock *RTypeReplaced1) Replace1(f rt1.RType1) {
+        _mock.Called(f)
+        return
+    }
+    ```
+
+=== "after"
+
+    ```go 
+    // Replace2 provides a mock function for the type RTypeReplaced1
+    func (_mock *RTypeReplaced1) Replace1(f rt2.RType2) {
+        _mock.Called(f)
+        return
+    }
+    ```
+
+## Background
+
+This parameter is useful if you need to need to work around packages that use internal types. Take for example the situation found [here](https://github.com/vektra/mockery/issues/864#issuecomment-2567788637), noted by [RangelReale](https://github.com/RangelReale).

e2e/test_infinite_mocking.sh

@@ -4,6 +4,7 @@
 
 # New mocks may legimitately be created, so we run mockery once first
 num_files_before=$(find . -type f | wc -l)
+export MOCKERY_FORCE_FILE_WRITE="true"
 go run github.com/go-task/task/v3/cmd/task mocks.generate
 num_files_after=$(find . -type f | wc -l)