Backport to 2.7.x branch: Add specific and actionable instructions to stale lockfile errors (#12699)

src/python/pants/backend/python/lint/pylint/subsystem.py

@@ -73,6 +73,7 @@ class Pylint(PythonToolBase):
     default_lockfile_resource = ("pants.backend.python.lint.pylint", "lockfile.txt")
     default_lockfile_path = "src/python/pants/backend/python/lint/pylint/lockfile.txt"
     default_lockfile_url = git_url(default_lockfile_path)
+    uses_requirements_from_source_plugins = True
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/python/subsystems/python_tool_base.py

@@ -9,7 +9,13 @@
 from pants.backend.python.target_types import ConsoleScript, EntryPoint, MainSpecification
 from pants.backend.python.util_rules.interpreter_constraints import InterpreterConstraints
 from pants.backend.python.util_rules.lockfile_metadata import calculate_invalidation_digest
-from pants.backend.python.util_rules.pex import Lockfile, LockfileContent, PexRequirements
+from pants.backend.python.util_rules.pex import (
+    Lockfile,
+    LockfileContent,
+    PexRequirements,
+    ToolCustomLockfile,
+    ToolDefaultLockfile,
+)
 from pants.engine.fs import FileContent
 from pants.option.errors import OptionsError
 from pants.option.subsystem import Subsystem
@@ -38,6 +44,7 @@ class PythonToolRequirementsBase(Subsystem):
     register_lockfile: ClassVar[bool] = False
     default_lockfile_resource: ClassVar[tuple[str, str] | None] = None
     default_lockfile_url: ClassVar[str | None] = None
+    uses_requirements_from_source_plugins: ClassVar[bool] = False
 
     @classmethod
     def register_options(cls, register):
@@ -143,17 +150,23 @@ def pex_requirements(
 
         if self.lockfile == DEFAULT_TOOL_LOCKFILE:
             assert self.default_lockfile_resource is not None
-            return LockfileContent(
+            return ToolDefaultLockfile(
                 file_content=FileContent(
                     f"{self.options_scope}_default_lockfile.txt",
                     importlib.resources.read_binary(*self.default_lockfile_resource),
                 ),
                 lockfile_hex_digest=hex_digest,
+                options_scope_name=self.options_scope,
+                uses_project_interpreter_constraints=(not self.register_interpreter_constraints),
+                uses_source_plugins=self.uses_requirements_from_source_plugins,
             )
-        return Lockfile(
+        return ToolCustomLockfile(
             file_path=self.lockfile,
             file_path_description_of_origin=f"the option `[{self.options_scope}].lockfile`",
             lockfile_hex_digest=hex_digest,
+            options_scope_name=self.options_scope,
+            uses_project_interpreter_constraints=(not self.register_interpreter_constraints),
+            uses_source_plugins=self.uses_requirements_from_source_plugins,
         )
 
     @property

src/python/pants/backend/python/typecheck/mypy/subsystem.py

@@ -71,6 +71,7 @@ class MyPy(PythonToolBase):
     default_lockfile_resource = ("pants.backend.python.typecheck.mypy", "lockfile.txt")
     default_lockfile_path = "src/python/pants/backend/python/typecheck/mypy/lockfile.txt"
     default_lockfile_url = git_url(default_lockfile_path)
+    uses_requirements_from_source_plugins = True
 
     @classmethod
     def register_options(cls, register):

src/python/pants/backend/python/util_rules/pex.py

@@ -58,6 +58,7 @@
 from pants.engine.rules import Get, MultiGet, collect_rules, rule
 from pants.python.python_repos import PythonRepos
 from pants.python.python_setup import InvalidLockfileBehavior, PythonSetup
+from pants.util.docutil import doc_url
 from pants.util.frozendict import FrozenDict
 from pants.util.logging import LogLevel
 from pants.util.meta import frozen_after_init
@@ -78,6 +79,23 @@ class LockfileContent:
     lockfile_hex_digest: str | None
 
 
+@dataclass(frozen=True)
+class _ToolLockfileMixin:
+    options_scope_name: str
+    uses_source_plugins: bool
+    uses_project_interpreter_constraints: bool
+
+
+@dataclass(frozen=True)
+class ToolDefaultLockfile(LockfileContent, _ToolLockfileMixin):
+    pass
+
+
+@dataclass(frozen=True)
+class ToolCustomLockfile(Lockfile, _ToolLockfileMixin):
+    pass
+
+
 @frozen_after_init
 @dataclass(unsafe_hash=True)
 class PexRequirements:
@@ -587,37 +605,82 @@ def _validate_metadata(
     if validation:
         return
 
-    message_parts = [
-        f"Invalid lockfile for PEX request `{request.output_filename}`.",
-        "\n",
-    ]
+    def tool_message_parts(
+        requirements: (ToolCustomLockfile | ToolDefaultLockfile),
+    ) -> Iterator[str]:
 
-    if InvalidLockfileReason.INVALIDATION_DIGEST_MISMATCH in validation.failure_reasons:
-        message_parts.append(
-            "The requirements set for this PEX request are different to the requirements set when "
-            "the lockfile was generated. To fix this, you will need to regenerate the lockfile. "
-        )
-        message_parts.append(
-            f"(Expected requirements digest: {requirements.lockfile_hex_digest}, "
-            f"actual: {metadata.requirements_invalidation_digest})"
-        )
-        message_parts.append("\n")
-
-    if InvalidLockfileReason.INTERPRETER_CONSTRAINTS_MISMATCH in validation.failure_reasons:
-        message_parts.append(
-            "The lockfile was generated under interpreter constraints "
-            f"({ metadata.valid_for_interpreter_constraints }) that are incompatible with the "
-            f"constraints set in the project ({request.interpreter_constraints }). If you have "
-            "overridden your project's interpreter constraints, you can update them to specify a "
-            "subset of the interpreters specified in the lockfile. If  not, you will need to "
-            "regenerate your lockfile. "
+        tool_name = requirements.options_scope_name
+        uses_source_plugins = requirements.uses_source_plugins
+        uses_project_interpreter_constraints = requirements.uses_project_interpreter_constraints
+
+        yield "You are using "
+
+        if isinstance(requirements, ToolDefaultLockfile):
+            yield "the `<default>` lockfile provided by Pants "
+        elif isinstance(requirements, ToolCustomLockfile):
+            yield f"the lockfile at {requirements.file_path} "
+
+        yield (
+            f"to install the tool `{tool_name}`, but it is not compatible with your "
+            "configuration: "
+            "\n\n"
         )
 
-    message_parts.append(
-        "To regenerate the lockfile, follow the instructions in the header of the lockfile."
-    )
+        if InvalidLockfileReason.INVALIDATION_DIGEST_MISMATCH in validation.failure_reasons:
+            yield (
+                "- You have set different requirements than those used to generate the lockfile. "
+                f"You can fix this by not setting `[{tool_name}].version`, "
+            )
+
+            if uses_source_plugins:
+                yield f"`[{tool_name}].source_plugins`, "
+
+            yield (
+                f"and `[{tool_name}].extra_requirements`, or by using a new "
+                "custom lockfile."
+                "\n"
+            )
 
-    message = "\n".join(message_parts).strip()
+        if InvalidLockfileReason.INTERPRETER_CONSTRAINTS_MISMATCH in validation.failure_reasons:
+            yield (
+                f"- You have set interpreter constraints (`{request.interpreter_constraints}`) that "
+                "are not compatible with those used to generate the lockfile "
+                f"(`{metadata.valid_for_interpreter_constraints}`). "
+            )
+            if not uses_project_interpreter_constraints:
+                yield (
+                    f"You can fix this by not setting `[{tool_name}].interpreter_constraints`, "
+                    "or by using a new custom lockfile. "
+                )
+            else:
+                yield (
+                    f"`{tool_name}` determines its interpreter constraints based on your code's own "
+                    "constraints. To fix this error, you can either change your code's constraints "
+                    f"(see {doc_url('python-interpreter-compatibility')}) or by generating a new "
+                    "custom lockfile. "
+                )
+            yield "\n"
+
+        yield "\n"
+
+        if not isinstance(requirements, ToolCustomLockfile):
+            yield (
+                "To generate a custom lockfile based on your current configuration, set "
+                f"`[{tool_name}].lockfile` to where you want to create the lockfile, then run "
+                f"`./pants generate-lockfiles --resolve={tool_name}`. "
+            )
+        else:
+            yield (
+                "To regenerate your lockfile based on your current configuration, run "
+                f"`./pants generate-lockfiles --resolve={tool_name}`. "
+            )
+
+    message: str
+    if isinstance(requirements, (ToolCustomLockfile, ToolDefaultLockfile)):
+        message = "".join(tool_message_parts(requirements)).strip()
+    else:
+        # TODO: Replace with an actual value once user lockfiles are supported
+        assert False
 
     if python_setup.invalid_lockfile_behavior == InvalidLockfileBehavior.error:
         raise ValueError(message)