feat(transformer): add Redocly bundling support with jentic-openapi-bundler-redocly

Introduce `jentic-openapi-bundler-redocly` package to enable Redocly-based OpenAPI bundling:

- Implement `RedoclyBundler` bundling strategy within the new package.
- Add CLI and entry-point configuration to support plugin discovery and extensibility.
- Update `jentic-openapi-transformer` with Redocly bundling integration.
- Introduce comprehensive test coverage for Redocly bundling edge cases and CLI compatibility.
- Update workflows (release/pre-release) and `pyproject.toml` to include new package.
- Add documentation and changelog entries for Redocly support.
- Adapt Spectral Validator and Validator packages to changes in subprocess result

Author: frantuma

.github/workflows/ci.yml

@@ -73,6 +73,8 @@ jobs:
         uses: astral-sh/setup-uv@v4
       - name: Set up Python
         run: uv python install ${{ matrix.python }}
+      - name: Install Redocly CLI
+        run: npm install -g @redocly/cli@latest
       - name: Install deps (with dev)
         run: uv sync
       - name: Pytest (transformer)
@@ -123,3 +125,26 @@ jobs:
         run: uv sync
       - name: Pytest (validator-spectral)
         run: uv run --package jentic-openapi-validator-spectral pytest -q packages/jentic-openapi-validator-spectral/tests
+
+  test_bundler_redocly:
+    name: Test (jentic-openapi-bundler-redocly)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+      - name: Set up Python
+        run: uv python install ${{ matrix.python }}
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install Redocly CLI
+        run: npm install -g @redocly/cli@latest
+      - name: Install deps (with dev)
+        run: uv sync
+      - name: Pytest (bundler-redocly)
+        run: uv run --package jentic-openapi-bundler-redocly -q pytest packages/jentic-openapi-bundler-redocly/tests

.github/workflows/pre-release.yml

@@ -35,6 +35,9 @@ jobs:
       - name: Install Spectral CLI
         run: npm install -g @stoplight/spectral-cli
 
+      - name: Install Redocly CLI
+        run: npm install -g @redocly/cli@latest
+
       - name: Install dependencies
         run: uv sync
 
@@ -48,6 +51,7 @@ jobs:
           uv run --package jentic-openapi-transformer pytest packages/jentic-openapi-transformer/tests -v
           uv run --package jentic-openapi-validator pytest packages/jentic-openapi-validator/tests -v
           uv run --package jentic-openapi-validator-spectral pytest packages/jentic-openapi-validator-spectral/tests -v
+          uv run --package jentic-openapi-bundler-redocly pytest packages/jentic-openapi-bundler-redocly/tests -v
 
       - name: Get next version for pre-release
         id: next_version
@@ -64,6 +68,7 @@ jobs:
           uv build --package jentic-openapi-transformer
           uv build --package jentic-openapi-validator
           uv build --package jentic-openapi-validator-spectral
+          uv build --package jentic-openapi-bundler-redocly
 
       - name: Create pre-release
         env:
@@ -84,4 +89,5 @@ jobs:
           uv publish --package jentic-openapi-parser
           uv publish --package jentic-openapi-transformer
           uv publish --package jentic-openapi-validator
-          uv publish --package jentic-openapi-validator-spectral
+          uv publish --package jentic-openapi-validator-spectral
+          uv publish --package jentic-openapi-bundler-redocly

.github/workflows/release.yml

@@ -50,6 +50,9 @@ jobs:
       - name: Install Spectral CLI
         run: npm install -g @stoplight/spectral-cli
 
+      - name: Install Redocly CLI
+        run: npm install -g @redocly/cli@latest
+
       - name: Install dependencies
         run: uv sync
 
@@ -130,6 +133,7 @@ jobs:
           uv run --package jentic-openapi-transformer pytest packages/jentic-openapi-transformer/tests -v
           uv run --package jentic-openapi-validator pytest packages/jentic-openapi-validator/tests -v
           uv run --package jentic-openapi-validator-spectral pytest packages/jentic-openapi-validator-spectral/tests -v
+          uv run --package jentic-openapi-bundler-redocly pytest packages/jentic-openapi-bundler-redocly/tests -v
 
       - name: Simulate version bump (DRY RUN)
         if: steps.check_release.outputs.release_needed == 'true' && env.DRY_RUN == 'true'
@@ -141,6 +145,7 @@ jobs:
           echo "  - packages/jentic-openapi-transformer/pyproject.toml"  
           echo "  - packages/jentic-openapi-validator/pyproject.toml"
           echo "  - packages/jentic-openapi-validator-spectral/pyproject.toml"
+          echo "  - packages/jentic-openapi-bundler-redocly/pyproject.toml"
           echo "🔍 DRY RUN: Would create git tag: v${{ steps.version_info.outputs.next_version }}"
 
       - name: Handle first release (DRY RUN)
@@ -176,6 +181,7 @@ jobs:
           echo "- jentic-openapi-transformer ${CURRENT_VERSION}" >> CHANGELOG.md
           echo "- jentic-openapi-validator ${CURRENT_VERSION}" >> CHANGELOG.md
           echo "- jentic-openapi-validator-spectral ${CURRENT_VERSION}" >> CHANGELOG.md
+          echo "- jentic-openapi-bundler-redocly ${CURRENT_VERSION}" >> CHANGELOG.md
           echo "" >> CHANGELOG.md
           echo "### Features" >> CHANGELOG.md
           echo "- Initial release of Jentic OpenAPI Tools" >> CHANGELOG.md
@@ -209,6 +215,7 @@ jobs:
           uv build --package jentic-openapi-transformer
           uv build --package jentic-openapi-validator
           uv build --package jentic-openapi-validator-spectral
+          uv build --package jentic-openapi-bundler-redocly
 
       - name: Show build artifacts
         if: steps.check_release.outputs.release_needed == 'true'
@@ -231,6 +238,7 @@ jobs:
           echo "  - jentic-openapi-transformer"
           echo "  - jentic-openapi-validator"
           echo "  - jentic-openapi-validator-spectral"
+          echo "  - jentic-openapi-bundler-redocly"
 
       - name: Create GitHub Release (REAL)
         if: steps.check_release.outputs.release_needed == 'true' && env.DRY_RUN == 'false'
@@ -259,6 +267,7 @@ jobs:
           uv publish --package jentic-openapi-transformer
           uv publish --package jentic-openapi-validator
           uv publish --package jentic-openapi-validator-spectral
+          uv publish --package jentic-openapi-bundler-redocly
 
       - name: Release Summary (DRY RUN)
         if: steps.check_release.outputs.release_needed == 'true' && env.DRY_RUN == 'true'

README.md

@@ -18,6 +18,7 @@ uv run --package jentic-openapi-parser       pytest packages/jentic-openapi-pars
 uv run --package jentic-openapi-transformer  pytest packages/jentic-openapi-transformer/tests -q
 uv run --package jentic-openapi-validator    pytest packages/jentic-openapi-validator/tests -q
 uv run --package jentic-openapi-validator-spectral    pytest packages/jentic-openapi-validator-spectral/tests -q
+uv run --package jentic-openapi-bundler-redocly    pytest packages/jentic-openapi-bundler-redocly/tests -q
 ```
 
 ### Run linting
@@ -32,6 +33,7 @@ uv build --package jentic-openapi-parser
 uv build --package jentic-openapi-transformer
 uv build --package jentic-openapi-validator
 uv build --package jentic-openapi-validator-spectral
+uv build --package jentic-openapi-bundler-redocly
 ```
 
 ### Conventional Commits

packages/jentic-openapi-bundler-redocly/README.md

@@ -0,0 +1,18 @@
+# jentic-openapi-bundler-redocly
+
+## Running the tests
+To run these integration tests, you would need both packages installed. You can test this setup by:
+
+1. **Installing both packages in development mode:**
+
+```
+# From the project root
+uv run pip install -e packages/jentic-openapi-transformer
+uv run pip install -e packages/jentic-openapi-bundler-redocly
+```
+
+2. **Running the integration test:**
+
+```
+uv run --package jentic-openapi-transformer pytest packages/jentic-openapi-transformer/tests/test_bundle_redocly.py -v
+```

packages/jentic-openapi-bundler-redocly/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "jentic-openapi-bundler-redocly"
+version = "0.1.0"
+description = "Jentic OpenAPI Redocly Bundler Strategy"
+readme = "README.md"
+authors = [{ name = "Jentic", email = "hello@jentic.com" }]
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+dependencies = [
+  "jentic-openapi-common",
+  "jentic-openapi-transformer",
+  "importlib-resources>=1.3.0;python_version<'3.9'"
+]
+
+[project.urls]
+Homepage = "https://github.com/jentic/jentic-openapi-tools"
+
+[tool.uv.sources]
+jentic-openapi-transformer = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.8.15,<0.9.0"]
+build-backend = "uv_build"
+
+[project.entry-points."jentic.openapi_bundler_strategies"]
+redocly = "jentic_openapi_bundler_redocly.redocly_bundler:RedoclyBundler"
+
+

packages/jentic-openapi-bundler-redocly/src/jentic_openapi_bundler_redocly/__init__.py

@@ -0,0 +1,3 @@
+from .redocly_bundler import RedoclyBundler
+
+__all__ = ["RedoclyBundler"]

packages/jentic-openapi-bundler-redocly/src/jentic_openapi_bundler_redocly/redocly_bundler.py

@@ -0,0 +1,66 @@
+from typing import Any
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+from jentic_openapi_transformer.strategies.base import BaseBundlerStrategy
+
+from jentic_openapi_common import run_checked, SubprocessExecutionError
+
+
+class RedoclyBundler(BaseBundlerStrategy):
+    def __init__(self, redocly_path: str = "redocly"):
+        """
+        Initialize the RedoclyBundler.
+
+        Args:
+            redocly_path: Path to the redocly CLI executable (default: "redocly")
+        """
+        self.redocly_path = redocly_path
+
+    def accepts(self) -> list[str]:
+        return ["uri"]
+
+    def bundle(self, document: str | dict, base_url: str | None = None) -> Any:
+        try:
+            assert isinstance(document, str)
+            return self._bundle(document, base_url)
+        except Exception as e:
+            # TODO add to parser/validation chain result
+            raise e
+
+    def _bundle(self, document: str, base_url: str | None = None) -> str:
+        try:
+            parsed_doc_url = urlparse(document)
+            doc_path = url2pathname(parsed_doc_url.path)
+            # Build redocly command
+            cmd = [
+                self.redocly_path,
+                "bundle",
+                doc_path,
+                "--ext",
+                "json",
+                "--lint-config",
+                "off",
+                "--force",
+                # "--remove-unused-components", # TODO, raises errors in redocly for some reason
+            ]
+            result = run_checked(cmd)
+        except SubprocessExecutionError as e:
+            # only timeout and OS errors, as run_checked has default `fail_on_error = False`
+            raise e
+
+        if result.stdout:
+            # When using `--force` Redocly tries bundling even on errors
+            output_lines = result.stdout.splitlines()
+            if output_lines and output_lines[-1].startswith("Created a bundle"):
+                output_lines = output_lines[:-1]
+
+            if result.returncode != 0 and result.stderr:
+                # TODO we need to add any errors to the parser/validation chain result
+                print(f"Error parsing document: {result.stderr}")
+
+            return "\n".join(output_lines)
+        else:
+            err = (result.stderr or "").strip()
+            msg = err or f"Redocly exited with code {result.returncode}"
+            raise Exception(msg)