Gazelle: Unintuitive error message for 'multiple targets' in package generation mode with `py_binary` targets

As the title states, this report highlights an unintuitive error message.

The problem presents itself when 1) `# gazelle:python_generation_mode package` is used and 2) a python file is used both as a library (imported by other python files) and a binary (containing a `main` method). Gazelle then tries to generate 2 targets, one for the package `py_library` target and another `py_binary` target for the python file. When this happens, an error message like the following is produced (see below for the MRE):

```
2024/12/26 08:39:05 ERROR: failed to validate dependencies for target "//app:app": multiple targets (//lib:a, //lib) may be imported with "lib.a" at line 1 in "app/app.py" - this must be fixed using the "gazelle:resolve" directive
"lib" at line 1 from "app/app.py" is an invalid dependency: possible solutions:
1. Add it as a dependency in the requirements.txt file.
2. Instruct Gazelle to resolve to a known dependency using the gazelle:resolve directive.
3. Ignore it with a comment '# gazelle:ignore lib' in the Python file.
```

This error message is unintuitive because it is not clear why there are multiple targets, especially for engineers who aren't part of the infra team maintaining Gazelle and don't fully understand its internals. Also, none of the 3 solutions recommended by the error message are correct; the real solution is to split the `main` method from `lib/a.py` into its own file (e.g. `lib/a_main.py`) which wouldn't be imported by anything else.

It seems to me that python files which serve as both libraries and binaries are fundamentally incompatible with `package` generation mode, but I'm still new to Gazelle so I might be missing something.

### Proposed Solution
Gazelle already has all the information it needs to provide a better error message. Some ideas for improving the DX:
1. Fail hard when in `package` mode and any python file has a dependency on another file with a `main` function. This would be my preferred solution because its the most explicit, but not sure if it will break other setups.
1. In the case where the above message would be printed, include a 4th option to the suggested solutions in the error message: `4. Split the 'if '__name__' == '__main__' entrypoint function into a separate '.py' file, to avoid including its other contents in multiple targets.`

### MRE

```
# BUILD.bazel
# gazelle:python_generation_mode package
```

```python
# lib/a.py
def add(a: int, b: int) -> int:
return a + b

if __name__ == "__main__":
print(add(1, 2))
```

```python
# app/app.py
import lib.a as a

if __name__ == "__main__":
print(a.add(1, 2))
```

### Bonus
There might be some relation between this request and #2443. After resolving by splitting out the `main` method, e.g. into `a_main.py`, the generated targets for the `lib` package look like this:

```
load("@aspect_rules_py//py:defs.bzl", "py_binary", "py_library")

py_binary(
name = "a",
srcs = ["a_main.py"],
visibility = ["//:__subpackages__"],
deps = [":lib"],
)

py_library(
name = "lib",
srcs = [
"a.py",
"a_main.py", # <-- unnecessary src
],
visibility = ["//:__subpackages__"],
)
```

Importantly, `a_main.py` gets included in the package-level `py_library` target even though it will never be used. If it was used, we would run into the error above.

Reproduce the MRE using BUILD.bazel, lib/a.py, and app/app.py with package generation mode, then inspect Gazelle's dependency validation and error-reporting path. Compare the generated targets and determine whether the diagnostic should explain the library/binary conflict or reject it; done means the case has a clear, tested diagnostic that does not suggest the three incorrect fixes.

Escrito por el modelo de indexación a partir del texto del issue.