feat(breaking): generate changelog from two code reports (#45790)

* feat(breaking): generate changelog from two code reports

Add a fast-path to \�zpysdk breaking\ that compares two pre-built
code reports directly, without requiring a package directory, wheel
build, or PyPI install.

Changes:
- breaking.py: short-circuit run() when --source-report and
  --target-report are both provided, delegating to new
  _run_from_reports() which calls detect_breaking_changes.py directly
- detect_breaking_changes.py: fix test_compare_reports() to handle
  absolute report paths (only joins with pkg_dir when path is relative)
- test_changelog.py: add test_compare_reports_with_absolute_paths to
  verify absolute path handling end-to-end

Usage:
  azpysdk breaking --source-report stable.json --target-report current.json --changelog

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* format

* docs(breaking): add generate-changelog-from-reports section to README

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

eng/tools/azure-sdk-tools/azpysdk/breaking.py

@@ -1,6 +1,7 @@
 import argparse
 import os
 import sys
+import tempfile
 
 from typing import Optional, List
 from subprocess import CalledProcessError, check_call
@@ -89,6 +90,12 @@ def run(self, args: argparse.Namespace) -> int:
         logger.info("Running breaking check...")
 
         set_envvar_defaults()
+
+        # Fast path: if two pre-built code reports are provided, compare them directly
+        # without needing a package directory, build, or install step.
+        if getattr(args, "source_report", None) and getattr(args, "target_report", None):
+            return self._run_from_reports(args)
+
         targeted = self.get_targeted_directories(args)
 
         results: List[int] = []
@@ -159,3 +166,37 @@ def run(self, args: argparse.Namespace) -> int:
                 continue
 
         return max(results) if results else 0
+
+    def _run_from_reports(self, args: argparse.Namespace) -> int:
+        """Compare two pre-built code reports directly, skipping package build and install."""
+        source = os.path.abspath(args.source_report)
+        target = os.path.abspath(args.target_report)
+
+        # Use a temporary root directory, but create a subdirectory whose basename is derived
+        # from the source report path so detect_breaking_changes.py can infer the package name
+        # correctly from os.path.basename(pkg_dir).
+        with tempfile.TemporaryDirectory() as tmp_root:
+            # Heuristic: use the parent directory name of the source report as the package name.
+            pkg_name = os.path.basename(os.path.dirname(source))
+            tmp_pkg_dir = os.path.join(tmp_root, pkg_name)
+            os.makedirs(tmp_pkg_dir, exist_ok=True)
+
+            cmd = [
+                sys.executable,
+                os.path.join(BREAKING_CHECKER_PATH, "detect_breaking_changes.py"),
+                "--target",
+                tmp_pkg_dir,
+                "--source-report",
+                source,
+                "--target-report",
+                target,
+            ]
+            if getattr(args, "changelog", False):
+                cmd.append("--changelog")
+
+            try:
+                check_call(cmd)
+            except CalledProcessError as e:
+                logger.error(f"Breaking change report generation failed: {e}")
+                return 1
+        return 0

scripts/breaking_changes_checker/README.md

@@ -138,3 +138,45 @@ Example:
 ```
 C:\azure-sdk-for-python\sdk\storage\azure-storage-blob> azpysdk breaking . --source-report ./source_code_report.json --target-report ./target_code_report.json
 ```
+
+### Generate changelog from two code reports
+
+When both `--source-report` and `--target-report` are provided together with the `--changelog` flag, the tool skips the package build and PyPI install steps entirely and generates the changelog by comparing the two reports directly. This is the fastest way to produce a changelog when you already have code reports for both versions.
+
+**Step 1:** Generate a code report for the stable (old) version:
+
+```
+C:\azure-sdk-for-python\sdk\storage\azure-storage-blob> azpysdk breaking . --code-report
+```
+
+Rename the output file: `mv code_report.json stable_report.json`
+
+**Step 2:** After updating your code, generate a report for the new version:
+
+```
+C:\azure-sdk-for-python\sdk\storage\azure-storage-blob> azpysdk breaking . --code-report
+```
+
+Rename the output file: `mv code_report.json current_report.json`
+
+**Step 3:** Generate the changelog by comparing the two reports:
+
+```
+C:\azure-sdk-for-python\sdk\storage\azure-storage-blob> azpysdk breaking --source-report ./stable_report.json --target-report ./current_report.json --changelog
+```
+
+Example output:
+
+```
+===== changelog start =====
+### Features Added
+
+  - Client `BlobServiceClient` added method `list_blobs_flat`
+
+### Breaking Changes
+
+  - Deleted or renamed client method `BlobServiceClient.list_blobs`
+===== changelog end =====
+```
+
+> **Note:** When `--source-report` and `--target-report` are both specified, you do not need to pass a positional package directory argument, but you should still run the command from the package's root directory so that the package name is inferred correctly for opt-in and ignore-rule behavior. The `--changelog` flag is optional — omitting it will report only breaking changes and exit with code 1 if any are found.

scripts/breaking_changes_checker/detect_breaking_changes.py

@@ -443,9 +443,18 @@ def build_library_report(target_module: str) -> Dict:
 def test_compare_reports(pkg_dir: str, changelog: bool, source_report: str = "stable.json", target_report: str = "current.json") -> None:
     package_name = os.path.basename(pkg_dir)
 
-    with open(os.path.join(pkg_dir, source_report), "r") as fd:
+    # Preserve the original argument values so we can decide later whether cleanup is safe.
+    original_source_report = source_report
+    original_target_report = target_report
+
+    if not os.path.isabs(source_report):
+        source_report = os.path.join(pkg_dir, source_report)
+    if not os.path.isabs(target_report):
+        target_report = os.path.join(pkg_dir, target_report)
+
+    with open(source_report, "r") as fd:
         stable = json.load(fd)
-    with open(os.path.join(pkg_dir, target_report), "r") as fd:
+    with open(target_report, "r") as fd:
         current = json.load(fd)
 
     if "azure-mgmt-" in package_name:
@@ -461,10 +470,25 @@ def test_compare_reports(pkg_dir: str, changelog: bool, source_report: str = "st
         post_processing_checkers = POST_PROCESSING_CHECKERS
     )
     if changelog:
-        checker = ChangelogTracker(stable, current, package_name, checkers = CHECKERS, ignore = IGNORE_BREAKING_CHANGES, post_processing_checkers = POST_PROCESSING_CHECKERS)
+        checker = ChangelogTracker(
+            stable,
+            current,
+            package_name,
+            checkers = CHECKERS,
+            ignore = IGNORE_BREAKING_CHANGES,
+            post_processing_checkers = POST_PROCESSING_CHECKERS,
+        )
     checker.run_checks()
 
-    remove_json_files(pkg_dir)
+    # Only clean up reports that were generated into pkg_dir with default, non-absolute names.
+    cleanup_default_reports = (
+        original_source_report == "stable.json"
+        and original_target_report == "current.json"
+        and not os.path.isabs(original_source_report)
+        and not os.path.isabs(original_target_report)
+    )
+    if cleanup_default_reports:
+        remove_json_files(pkg_dir)
 
     print(checker.report_changes())
 

scripts/breaking_changes_checker/tests/test_changelog.py

@@ -11,6 +11,7 @@
 from checkers.added_method_overloads_checker import AddedMethodOverloadChecker
 from breaking_changes_checker.changelog_tracker import ChangelogTracker, BreakingChangesTracker
 from breaking_changes_checker.detect_breaking_changes import main
+from breaking_changes_checker.detect_breaking_changes import test_compare_reports as compare_reports
 
 
 def test_changelog_flag():
@@ -681,3 +682,18 @@ def test_added_overload():
     msg, _, *args = bc.features_added[1]
     assert msg == AddedMethodOverloadChecker.message["default"]
     assert args == ['azure.contoso', 'class_name', 'two', 'def two(foo: JSON)']
+
+
+def test_compare_reports_with_absolute_paths(capsys):
+    """Verify test_compare_reports accepts absolute paths for source/target reports."""
+    tests_dir = os.path.dirname(__file__)
+    source_report = os.path.abspath(os.path.join(tests_dir, "examples", "code-reports", "content-safety", "stable.json"))
+    target_report = os.path.abspath(os.path.join(tests_dir, "examples", "code-reports", "content-safety", "current.json"))
+    pkg_dir = tests_dir  # pkg_dir must exist and is still used (e.g., for package_name and cleanup); its value is independent of using absolute report paths
+
+    # Should not raise; changelog=True means no SystemExit(1) even if breaking changes exist
+    compare_reports(pkg_dir, changelog=True, source_report=source_report, target_report=target_report)
+
+    captured = capsys.readouterr()
+    assert "===== changelog start =====" in captured.out
+    assert "===== changelog end =====" in captured.out