imbi-plugin-github 2.38.0__tar.gz → 2.39.0__tar.gz

{imbi_plugin_github-2.38.0 → imbi_plugin_github-2.39.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: imbi-plugin-github
-Version: 2.38.0
+Version: 2.39.0
 Summary: GitHub identity plugin for Imbi (github.com / GHEC / GHES)
 Author-email: "Gavin M. Roy" <gavinr@aweber.com>
 License-Expression: BSD-3-Clause
@@ -12,7 +12,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.14
 Requires-Dist: httpx>=0.27
-Requires-Dist: imbi-common[databases]==2.38.0
+Requires-Dist: imbi-common[databases]==2.39.0
 Requires-Dist: pydantic>=2
 Requires-Dist: pyjwt[crypto]>=2.8
 Description-Content-Type: text/markdown

{imbi_plugin_github-2.38.0 → imbi_plugin_github-2.39.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imbi-plugin-github"
-version = "2.38.0"
+version = "2.39.0"
 description = "GitHub identity plugin for Imbi (github.com / GHEC / GHES)"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -18,7 +18,7 @@ classifiers = [
 ]
 dependencies = [
   "httpx>=0.27",
-  "imbi-common[databases]==2.38.0",
+  "imbi-common[databases]==2.39.0",
   "pydantic>=2",
   "pyjwt[crypto]>=2.8",
 ]

{imbi_plugin_github-2.38.0 → imbi_plugin_github-2.39.0}/src/imbi/plugins/github/doctor.py

@@ -2,8 +2,9 @@
 
 Performs richer, GitHub-aware validation than the generic exists-in doctor:
 identifier is an integer, canonical URL follows the /repositories/{id} shape
-that the lifecycle plugin writes, dashboard link matches the API html_url, and
-the legacy github-repository link matches as well.
+that the lifecycle plugin writes, dashboard link matches the API html_url,
+the legacy github-repository link matches as well, and the repository
+``homepage`` points back at the project's Imbi page.
 
 A single analysis capability covers github.com, GHEC tenants, and GHES
 appliances: the GitHub host is resolved from the Integration's ``flavor`` +
@@ -53,8 +54,14 @@ _REPO_ID_RE = re.compile(r'.*/repositories/(\d+)$')
 # edge-shaped discrepancy (identifier, canonical URL shape, dashboard
 # link) is repaired by one ``ServiceWriteback`` so they share an id; the
 # legacy ``github-repository`` link is a separate ``LinkWriteback``.
+# The ``homepage`` repair is the one that writes *to* GitHub: it PATCHes
+# the repository so its homepage is the project's Imbi page.
 _REPAIR_EDGE = 'repair-edge'
 _REPAIR_GITHUB_LINK = 'repair-github-link'
+_REPAIR_HOMEPAGE = 'repair-homepage'
+_REMEDIATION_IDS = frozenset(
+    {_REPAIR_EDGE, _REPAIR_GITHUB_LINK, _REPAIR_HOMEPAGE}
+)
 
 
 async def _raise_on_401(response: httpx.Response) -> None:
@@ -554,6 +561,8 @@ class GitHubDoctor(AnalysisCapability):
                 )
             )
 
+        results.append(_homepage_item(ctx, body))
+
         return results
 
     async def remediate(  # noqa: C901 — flat sequence of guard clauses
@@ -573,7 +582,7 @@ class GitHubDoctor(AnalysisCapability):
         ``PluginAuthenticationFailed`` so the host can refresh the actor's
         identity and retry once.
         """
-        if remediation_id not in (_REPAIR_EDGE, _REPAIR_GITHUB_LINK):
+        if remediation_id not in _REMEDIATION_IDS:
             return await super().remediate(ctx, credentials, remediation_id)
 
         try:
@@ -593,9 +602,9 @@ class GitHubDoctor(AnalysisCapability):
         connection = _find_connection(ctx.service_connections, slug)
         # ``_REPAIR_EDGE`` creates a missing edge from GitHub, so a
         # missing connection is only fatal for the github-repository
-        # link repair (which never needs the edge but is only ever
-        # offered once the edge is present).
-        if connection is None and remediation_id == _REPAIR_GITHUB_LINK:
+        # link and homepage repairs (which never need the edge but are
+        # only ever offered once the edge is present).
+        if connection is None and remediation_id != _REPAIR_EDGE:
             return RemediationResult(
                 status='failed',
                 message=(
@@ -661,6 +670,9 @@ class GitHubDoctor(AnalysisCapability):
                 message='GitHub response did not include an html_url.',
             )
 
+        if remediation_id == _REPAIR_HOMEPAGE:
+            return await _repair_homepage(ctx, body, api_base, headers)
+
         if remediation_id == _REPAIR_GITHUB_LINK:
             if ctx.project_links.get('github-repository') == html_url:
                 return RemediationResult(
@@ -769,4 +781,129 @@ def _body_unavailable_items() -> list[AnalysisResultItem]:
             'warn',
             'Cannot verify github-repository link: repository fetch failed.',
         ),
+        _item(
+            'homepage-url-match',
+            'Homepage URL match',
+            'warn',
+            'Cannot verify the repository homepage: repository fetch failed.',
+        ),
     ]
+
+
+def _repo_homepage(body: dict[str, typing.Any]) -> str:
+    """Return the repository ``homepage``, normalising unset to ``''``.
+
+    GitHub reports an unset homepage as ``null`` on some flavors and as
+    the empty string on others; both mean "not set".
+    """
+    homepage = body.get('homepage')
+    return homepage if isinstance(homepage, str) else ''
+
+
+def _homepage_item(
+    ctx: PluginContext, body: dict[str, typing.Any]
+) -> AnalysisResultItem:
+    """Check that the repository ``homepage`` is the project's Imbi page.
+
+    The expected value is ``ctx.project_ui_url``, the same deep link the
+    lifecycle plugin writes on create / update.  It is ``None`` when the
+    API has no ``IMBI_UI_URL`` configured, in which case there is
+    nothing to compare against and no repair to offer.
+    """
+    expected = ctx.project_ui_url
+    actual = _repo_homepage(body)
+    if expected is None:
+        return _item(
+            'homepage-url-match',
+            'Homepage URL match',
+            'warn',
+            'Cannot verify the repository homepage: IMBI_UI_URL is not '
+            'configured on the API, so the project has no canonical '
+            'Imbi page URL.',
+        )
+    if actual == expected:
+        return _item(
+            'homepage-url-match',
+            'Homepage URL match',
+            'pass',
+            f"Repository homepage {actual!r} matches the project's Imbi page.",
+        )
+    offer = RemediationOffer(
+        id=_REPAIR_HOMEPAGE,
+        label="Set the repository homepage to the project's Imbi page",
+    )
+    if not actual:
+        return _item(
+            'homepage-url-match',
+            'Homepage URL match',
+            'warn',
+            'The repository has no homepage set. Use the Fix action to '
+            f"point it at the project's Imbi page {expected!r}.",
+            offer,
+        )
+    return _item(
+        'homepage-url-match',
+        'Homepage URL match',
+        'fail',
+        f"Repository homepage {actual!r} does not match the project's "
+        f'Imbi page {expected!r}. Use the Fix action to update it.',
+        offer,
+    )
+
+
+async def _repair_homepage(
+    ctx: PluginContext,
+    body: dict[str, typing.Any],
+    api_base: str,
+    headers: dict[str, str],
+) -> RemediationResult:
+    """PATCH the repository ``homepage`` to the project's Imbi page.
+
+    Unlike the edge / link repairs, which write back into Imbi, this
+    one writes to GitHub -- the same ``PATCH /repos/{owner}/{repo}``
+    the lifecycle plugin uses on update.  ``body`` is the freshly
+    fetched repository, so ``full_name`` reflects any rename or
+    transfer.  Idempotent: ``noop`` when GitHub already matches.
+    """
+    expected = ctx.project_ui_url
+    if expected is None:
+        return RemediationResult(
+            status='failed',
+            message=(
+                'IMBI_UI_URL is not configured on the API, so there is no '
+                'Imbi page URL to write as the repository homepage.'
+            ),
+        )
+    if _repo_homepage(body) == expected:
+        return RemediationResult(
+            status='noop',
+            message='Repository homepage already matches the Imbi page.',
+        )
+    full_name = body.get('full_name')
+    if not isinstance(full_name, str) or not full_name:
+        return RemediationResult(
+            status='failed',
+            message='GitHub response did not include a full_name.',
+        )
+    patch_url = f'{api_base}/repos/{full_name}'
+    try:
+        async with httpx.AsyncClient(
+            headers=headers,
+            timeout=_TIMEOUT,
+            event_hooks={'response': [_raise_on_401]},
+        ) as client:
+            resp = await client.patch(patch_url, json={'homepage': expected})
+    except httpx.TransportError as exc:
+        return RemediationResult(
+            status='failed',
+            message=f'Transport error patching {patch_url!r}: {exc}',
+        )
+    if not resp.is_success:
+        return RemediationResult(
+            status='failed',
+            message=f'HTTP {resp.status_code} patching {patch_url!r}.',
+        )
+    return RemediationResult(
+        status='fixed',
+        message=f'Set the repository homepage to {expected}.',
+    )

{imbi_plugin_github-2.38.0 → imbi_plugin_github-2.39.0}/src/imbi/plugins/github/plugin.py

@@ -410,8 +410,9 @@ class GitHubPlugin(Plugin):
                 description=(
                     'Validate the GitHub repository link (EXISTS_IN edge) '
                     'against the live GitHub API — identifier, canonical '
-                    'URL shape, and dashboard / github-repository links — '
-                    'and offer one-click repairs.'
+                    'URL shape, dashboard / github-repository links, and '
+                    "the repository homepage pointing at the project's "
+                    'Imbi page — and offer one-click repairs.'
                 ),
                 handler=GitHubDoctor,
             ),

{imbi_plugin_github-2.38.0 → imbi_plugin_github-2.39.0}/tests/test_doctor.py

@@ -1,5 +1,6 @@
 """Tests for the GitHub-native project-doctor analysis plugin."""
 
+import json
 import unittest
 
 import httpx
@@ -20,6 +21,7 @@ from imbi.plugins.github import _app_auth
 from imbi.plugins.github.doctor import (
     _REPAIR_EDGE,
     _REPAIR_GITHUB_LINK,
+    _REPAIR_HOMEPAGE,
     GitHubDoctor,
 )
 
@@ -27,7 +29,15 @@ _HOST = 'aweber.ghe.com'
 _API_BASE = 'https://api.aweber.ghe.com'
 _CANONICAL = f'{_API_BASE}/repositories/134741'
 _DASHBOARD = f'https://{_HOST}/aweber/demo'
-_REPO_PAYLOAD = {'id': 134741, 'html_url': _DASHBOARD, 'name': 'demo'}
+_UI_URL = 'https://imbi.example.com/projects/p'
+_REPO_PAYLOAD = {
+    'id': 134741,
+    'html_url': _DASHBOARD,
+    'name': 'demo',
+    'full_name': 'aweber/demo',
+    'homepage': _UI_URL,
+}
+_PATCH_URL = f'{_API_BASE}/repos/aweber/demo'
 
 _TPS_SLUG = 'aweber-github'
 _CREDS = {'access_token': 'gho_test'}
@@ -53,6 +63,7 @@ def _ctx(
     connections: list[ServiceConnection] | None = None,
     links: dict[str, str] | None = None,
     options: dict[str, str] | None = None,
+    project_ui_url: str | None = _UI_URL,
 ) -> PluginContext:
     if connections is None:
         connections = [
@@ -79,6 +90,7 @@ def _ctx(
         ),
         service_connections=connections,
         project_links=links if links is not None else default_links,
+        project_ui_url=project_ui_url,
     )
 
 
@@ -143,7 +155,7 @@ class AnalyzeTestCase(unittest.IsolatedAsyncioTestCase):
         plugin = GitHubDoctor()
         results = await plugin.analyze(_ctx(), _CREDS)
         by = _by_slug(results)
-        self.assertEqual(len(results), 8)
+        self.assertEqual(len(results), 9)
         self.assertEqual(by['exists-in'].status, 'pass')
         self.assertEqual(by['identifier-verified'].status, 'pass')
         self.assertEqual(by['canonical-url'].status, 'pass')
@@ -152,6 +164,7 @@ class AnalyzeTestCase(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(by['canonical-url-shape'].status, 'pass')
         self.assertEqual(by['dashboard-url-match'].status, 'pass')
         self.assertEqual(by['github-repository-link-match'].status, 'pass')
+        self.assertEqual(by['homepage-url-match'].status, 'pass')
 
     @respx.mock
     async def test_identifier_not_integer(self) -> None:
@@ -324,6 +337,52 @@ class AnalyzeTestCase(unittest.IsolatedAsyncioTestCase):
             'pass',
         )
 
+    @respx.mock
+    async def test_homepage_mismatch(self) -> None:
+        respx.get(_CANONICAL).mock(
+            return_value=httpx.Response(
+                200,
+                json={**_REPO_PAYLOAD, 'homepage': 'https://example.com'},
+            )
+        )
+        results = await GitHubDoctor().analyze(_ctx(), _CREDS)
+        item = _by_slug(results)['homepage-url-match']
+        self.assertEqual(item.status, 'fail')
+        self.assertIn(_UI_URL, item.description)
+        assert item.remediation is not None
+        self.assertEqual(item.remediation.id, _REPAIR_HOMEPAGE)
+
+    @respx.mock
+    async def test_homepage_unset(self) -> None:
+        # GitHub reports an unset homepage as null (or '' on some
+        # flavors); both are a soft finding with the repair offered.
+        for unset in (None, ''):
+            with self.subTest(homepage=unset):
+                respx.get(_CANONICAL).mock(
+                    return_value=httpx.Response(
+                        200, json={**_REPO_PAYLOAD, 'homepage': unset}
+                    )
+                )
+                results = await GitHubDoctor().analyze(_ctx(), _CREDS)
+                item = _by_slug(results)['homepage-url-match']
+                self.assertEqual(item.status, 'warn')
+                assert item.remediation is not None
+                self.assertEqual(item.remediation.id, _REPAIR_HOMEPAGE)
+
+    @respx.mock
+    async def test_homepage_unverifiable_without_ui_url(self) -> None:
+        # No IMBI_UI_URL on the API: nothing to compare against, and no
+        # repair is offered because there is nothing to write.
+        respx.get(_CANONICAL).mock(
+            return_value=httpx.Response(200, json=_REPO_PAYLOAD)
+        )
+        results = await GitHubDoctor().analyze(
+            _ctx(project_ui_url=None), _CREDS
+        )
+        item = _by_slug(results)['homepage-url-match']
+        self.assertEqual(item.status, 'warn')
+        self.assertIsNone(item.remediation)
+
     @respx.mock
     async def test_canonical_fetch_fails_401_no_token(self) -> None:
         respx.get(_CANONICAL).mock(return_value=httpx.Response(401))
@@ -614,6 +673,107 @@ class RemediateTestCase(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(result.status, 'noop')
         self.assertIsNone(ctx.link_writeback)
 
+    @respx.mock
+    async def test_homepage_repair_patches_github(self) -> None:
+        respx.get(_CANONICAL).mock(
+            return_value=httpx.Response(
+                200, json={**_REPO_PAYLOAD, 'homepage': ''}
+            )
+        )
+        patch = respx.patch(_PATCH_URL).mock(
+            return_value=httpx.Response(200, json=_REPO_PAYLOAD)
+        )
+        ctx = _ctx()
+        result = await GitHubDoctor().remediate(ctx, _CREDS, _REPAIR_HOMEPAGE)
+        self.assertEqual(result.status, 'fixed')
+        self.assertTrue(patch.called)
+        self.assertEqual(
+            json.loads(patch.calls.last.request.content),
+            {'homepage': _UI_URL},
+        )
+        # Writes to GitHub, not back into Imbi.
+        self.assertIsNone(ctx.link_writeback)
+        self.assertIsNone(ctx.service_writeback)
+
+    @respx.mock
+    async def test_homepage_repair_noop_when_correct(self) -> None:
+        respx.get(_CANONICAL).mock(
+            return_value=httpx.Response(200, json=_REPO_PAYLOAD)
+        )
+        patch = respx.patch(_PATCH_URL)
+        result = await GitHubDoctor().remediate(
+            _ctx(), _CREDS, _REPAIR_HOMEPAGE
+        )
+        self.assertEqual(result.status, 'noop')
+        self.assertFalse(patch.called)
+
+    async def test_homepage_repair_no_connection_failed(self) -> None:
+        result = await GitHubDoctor().remediate(
+            _ctx(connections=[]), _CREDS, _REPAIR_HOMEPAGE
+        )
+        self.assertEqual(result.status, 'failed')
+
+    @respx.mock
+    async def test_homepage_repair_without_ui_url_failed(self) -> None:
+        respx.get(_CANONICAL).mock(
+            return_value=httpx.Response(
+                200, json={**_REPO_PAYLOAD, 'homepage': ''}
+            )
+        )
+        result = await GitHubDoctor().remediate(
+            _ctx(project_ui_url=None), _CREDS, _REPAIR_HOMEPAGE
+        )
+        self.assertEqual(result.status, 'failed')
+
+    @respx.mock
+    async def test_homepage_repair_missing_full_name_failed(self) -> None:
+        payload = {**_REPO_PAYLOAD, 'homepage': ''}
+        del payload['full_name']
+        respx.get(_CANONICAL).mock(
+            return_value=httpx.Response(200, json=payload)
+        )
+        result = await GitHubDoctor().remediate(
+            _ctx(), _CREDS, _REPAIR_HOMEPAGE
+        )
+        self.assertEqual(result.status, 'failed')
+
+    @respx.mock
+    async def test_homepage_repair_patch_rejected_failed(self) -> None:
+        respx.get(_CANONICAL).mock(
+            return_value=httpx.Response(
+                200, json={**_REPO_PAYLOAD, 'homepage': ''}
+            )
+        )
+        respx.patch(_PATCH_URL).mock(return_value=httpx.Response(403))
+        result = await GitHubDoctor().remediate(
+            _ctx(), _CREDS, _REPAIR_HOMEPAGE
+        )
+        self.assertEqual(result.status, 'failed')
+
+    @respx.mock
+    async def test_homepage_repair_patch_401_propagates(self) -> None:
+        respx.get(_CANONICAL).mock(
+            return_value=httpx.Response(
+                200, json={**_REPO_PAYLOAD, 'homepage': ''}
+            )
+        )
+        respx.patch(_PATCH_URL).mock(return_value=httpx.Response(401))
+        with self.assertRaises(PluginAuthenticationFailed):
+            await GitHubDoctor().remediate(_ctx(), _CREDS, _REPAIR_HOMEPAGE)
+
+    @respx.mock
+    async def test_homepage_repair_transport_error_failed(self) -> None:
+        respx.get(_CANONICAL).mock(
+            return_value=httpx.Response(
+                200, json={**_REPO_PAYLOAD, 'homepage': ''}
+            )
+        )
+        respx.patch(_PATCH_URL).mock(side_effect=httpx.ConnectError('down'))
+        result = await GitHubDoctor().remediate(
+            _ctx(), _CREDS, _REPAIR_HOMEPAGE
+        )
+        self.assertEqual(result.status, 'failed')
+
     @respx.mock
     async def test_401_propagates_for_identity_retry(self) -> None:
         respx.get(_CANONICAL).mock(return_value=httpx.Response(401))