Report install errors and failures in JSON format

news/11316.feature.rst

@@ -0,0 +1 @@
+Report installation errors and dependency resolution failures in JSON format when using ``--report``.

src/pip/_internal/commands/install.py

@@ -445,6 +445,7 @@ def run(self, options: Values, args: list[str]) -> int:
             globally_managed=True,
         )
 
+        requirement_set = None
         try:
             reqs = self.get_requirements(args, options, finder, session)
 
@@ -580,6 +581,28 @@ def run(self, options: Values, args: list[str]) -> int:
                 )
             if summary := installed_packages_summary(installed, env):
                 write_output(summary)
+        except (InstallationError, CommandError, InstallWheelBuildError) as e:
+            # If a JSON report is requested, write the installation failure details
+            # in JSON format before re-raising the exception.
+            if options.json_report_file:
+                reqs_to_report = (
+                    requirement_set.requirements_to_install
+                    if requirement_set is not None
+                    and hasattr(requirement_set, "requirements_to_install")
+                    else []
+                )
+                report = InstallationReport(reqs_to_report)
+                report_dict = report.to_dict()
+                report_dict["error"] = {
+                    "code": e.__class__.__name__,
+                    "description": str(e),
+                }
+                if options.json_report_file == "-":
+                    print_json(data=report_dict)
+                else:
+                    with open(options.json_report_file, "w", encoding="utf-8") as f:
+                        json.dump(report_dict, f, indent=2, ensure_ascii=False)
+            raise e
         except OSError as error:
             show_traceback = self.verbosity >= 1
 

tests/functional/test_install_report.py

@@ -397,3 +397,40 @@ def test_install_report_to_stdout(
     report = json.loads(result.stdout)
     assert "install" in report
     assert len(report["install"]) == 1
+
+
+def test_install_report_error(script: PipTestEnvironment, tmp_path: Path) -> None:
+    report_path = tmp_path / "report.json"
+    script.pip(
+        "install",
+        "nonexistent-package-name-xyz",
+        "--no-index",
+        "--report",
+        str(report_path),
+        expect_error=True,
+    )
+    report = json.loads(report_path.read_text())
+    assert "error" in report
+    assert report["error"]["code"] == "DistributionNotFound"
+    assert (
+        "No matching distribution found for nonexistent-package-name-xyz"
+        in report["error"]["description"]
+    )
+
+
+def test_install_report_error_stdout(script: PipTestEnvironment) -> None:
+    result = script.pip(
+        "install",
+        "nonexistent-package-name-xyz",
+        "--no-index",
+        "--report",
+        "-",
+        expect_error=True,
+    )
+    report = json.loads(result.stdout)
+    assert "error" in report
+    assert report["error"]["code"] == "DistributionNotFound"
+    assert (
+        "No matching distribution found for nonexistent-package-name-xyz"
+        in report["error"]["description"]
+    )