What does .target represent in brew info --json=v2 for installed cask app artifacts?

[toobuntu]

Output of brew config

N/A

Output of brew doctor

N/A

Description of issue

I’m trying to understand the .target field of app artifacts in brew info --json=v2, and whether external commands can rely on .target for an installed cask being the resolved path of the installed app artifact.

I'm working on an external command that would like to consume the installed .app path after brew upgrade, and .target appears to already provide exactly that.

---

From experimenting, .target appears to behave differently depending on whether the cask is installed.

For a cask that is not installed, .target reflects the current configuration:

brew info --cask --json=v2 caffeine |
jq -r '.casks[].artifacts[]
       | select(has("app"))
       | .target'
/Applications/Caffeine.app

HOMEBREW_CASK_OPTS="--appdir=${HOME}/Applications" \
brew info --cask --json=v2 caffeine |
jq -r '.casks[].artifacts[]
       | select(has("app"))
       | .target' |
sed "s|$HOME|~|g"
~/Applications/Caffeine.app

For an installed cask, changing HOMEBREW_CASK_OPTS no longer changes .target:

brew info --cask --json=v2 domzilla-caffeine |
jq -r '.casks[].artifacts[]
       | select(has("app"))
       | .target'
/Applications/Caffeine.app

HOMEBREW_CASK_OPTS="--appdir=${HOME}/Applications" \
brew info --cask --json=v2 domzilla-caffeine |
jq -r '.casks[].artifacts[]
       | select(has("app"))
       | .target'
/Applications/Caffeine.app

The same behavior appears with both caffeine/domzilla-caffeine and freetube/pikachuexe/freetube/pikachuexe-freetube. So it seems that .target is computed from the current config for casks which are not installed, but reports the resolved installed location for installed casks.

Is that behavior intentional, and is it a stable API that external commands may rely on?

Relevant casks

N/A