evidentia-integrations 0.6.0__tar.gz

evidentia_integrations-0.6.0/.gitignore

@@ -0,0 +1,95 @@
+# v0.4.0 — frontend build output lands in the Python package's static
+# directory at wheel-assembly time via the hatchling build hook. The
+# .gitkeep file in static/ is tracked; everything else is regenerated.
+packages/evidentia-api/src/evidentia_api/static/assets/
+packages/evidentia-api/src/evidentia_api/static/index.html
+packages/evidentia-api/src/evidentia_api/static/*.js
+packages/evidentia-api/src/evidentia_api/static/*.css
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+# NB: `lib/` and `lib64/` above would otherwise also match
+# packages/evidentia-ui/src/lib/ (TypeScript utils). Scope to top-level
+# only — there's no real Python-venv lib/ we'd fail to ignore because
+# .venv/ and venv/ below cover that case.
+!packages/evidentia-ui/src/lib/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+# NOTE: uv.lock is committed for reproducible builds.
+# https://docs.astral.sh/uv/concepts/projects/sync/#locking-dependencies
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.cache
+coverage.xml
+*.cover
+.hypothesis/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Claude Code local state
+.claude/
+
+# Evidentia runtime — user project state (NOT bundled examples).
+# `.controlbridge/` and `/controlbridge.yaml` are kept ignored for the
+# lifetime of the shim (through v0.7.0) so legacy project workspaces
+# authored against v0.1.0 – v0.5.0 don't start leaking into git.
+.evidentia/
+.controlbridge/
+/evidentia.yaml
+/controlbridge.yaml
+*.local.yaml
+evidence/
+reports/
+risks/
+
+# Generated reports from examples (keep source files, ignore generated ones)
+examples/**/report.json
+examples/**/report.csv
+examples/**/report.md
+examples/**/report.oscal.json
+examples/**/risks.json

evidentia_integrations-0.6.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: evidentia-integrations
+Version: 0.6.0
+Summary: Output integrations for Jira and ServiceNow
+Project-URL: Homepage, https://github.com/allenfbyrd/evidentia
+Project-URL: Repository, https://github.com/allenfbyrd/evidentia
+Project-URL: Issues, https://github.com/allenfbyrd/evidentia/issues
+Project-URL: Changelog, https://github.com/allenfbyrd/evidentia/blob/main/CHANGELOG.md
+Author-email: Allen Byrd <allen@allenfbyrd.com>
+License-Expression: Apache-2.0
+Keywords: compliance,grc,jira,servicenow,ticketing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: evidentia-core<0.7.0,>=0.6.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: all
+Requires-Dist: jira>=3.8; extra == 'all'
+Requires-Dist: pysnc>=1.1; extra == 'all'
+Provides-Extra: jira
+Requires-Dist: jira>=3.8; extra == 'jira'
+Provides-Extra: servicenow
+Requires-Dist: pysnc>=1.1; extra == 'servicenow'
+Description-Content-Type: text/markdown
+
+# evidentia-integrations
+
+Output integrations for [Evidentia](https://github.com/allenfbyrd/evidentia). Push gaps to ticketing systems and export reports to industry-standard formats.
+
+## Provides
+
+- **Jira integration** — Create issues from ControlGap entries with framework-aware field population
+- **ServiceNow integration** — Create GRC records and incidents from gaps and risks
+- **OSCAL Assessment Results exporter** — Produce compliant OSCAL JSON for assessment reporting
+
+## Install
+
+```bash
+pip install evidentia-integrations[jira]
+pip install evidentia-integrations[servicenow]
+pip install evidentia-integrations[all]
+```
+
+License: Apache 2.0

evidentia_integrations-0.6.0/README.md

@@ -0,0 +1,19 @@
+# evidentia-integrations
+
+Output integrations for [Evidentia](https://github.com/allenfbyrd/evidentia). Push gaps to ticketing systems and export reports to industry-standard formats.
+
+## Provides
+
+- **Jira integration** — Create issues from ControlGap entries with framework-aware field population
+- **ServiceNow integration** — Create GRC records and incidents from gaps and risks
+- **OSCAL Assessment Results exporter** — Produce compliant OSCAL JSON for assessment reporting
+
+## Install
+
+```bash
+pip install evidentia-integrations[jira]
+pip install evidentia-integrations[servicenow]
+pip install evidentia-integrations[all]
+```
+
+License: Apache 2.0

evidentia_integrations-0.6.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "evidentia-integrations"
+version = "0.6.0"
+description = "Output integrations for Jira and ServiceNow"
+readme = "README.md"
+authors = [{name = "Allen Byrd", email = "allen@allenfbyrd.com"}]
+license = "Apache-2.0"
+requires-python = ">=3.12"
+keywords = ["grc", "compliance", "jira", "servicenow", "ticketing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+]
+dependencies = [
+    "evidentia-core>=0.6.0,<0.7.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+jira = ["jira>=3.8"]
+servicenow = ["pysnc>=1.1"]
+all = ["jira>=3.8", "pysnc>=1.1"]
+
+[project.urls]
+Homepage = "https://github.com/allenfbyrd/evidentia"
+Repository = "https://github.com/allenfbyrd/evidentia"
+Issues = "https://github.com/allenfbyrd/evidentia/issues"
+Changelog = "https://github.com/allenfbyrd/evidentia/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/evidentia_integrations"]
+
+[tool.uv.sources]
+evidentia-core = { workspace = true }

evidentia_integrations-0.6.0/src/evidentia_integrations/__init__.py

@@ -0,0 +1,9 @@
+"""Evidentia integrations: output integrations for Jira, ServiceNow, and OSCAL exporters."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("evidentia-integrations")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"

evidentia_integrations-0.6.0/src/evidentia_integrations/jira/__init__.py

@@ -0,0 +1,66 @@
+"""Jira output integration — push gaps as issues + bidirectional status sync.
+
+Public surface (imports from ``evidentia_integrations.jira``):
+
+- :class:`JiraClient` — httpx-based REST client; one instance per server.
+- :class:`JiraConfig` — typed configuration (base URL, project key, etc.).
+  Credentials come from environment variables; the config object never
+  carries the API token in its serialized form.
+- :class:`JiraIssue` — response shape from Jira's REST v3 API, narrowed
+  to the fields we actually care about.
+- :class:`JiraApiError`, :class:`JiraMappingError` — exception types.
+- :func:`gap_to_create_request` / :func:`jira_status_to_gap_status` —
+  pure functions exposing the mapping between Evidentia gaps and
+  Jira issues. Easy to unit-test without a live server.
+- :func:`push_gap_to_jira` / :func:`sync_gap_from_jira` — gap-level
+  helpers that combine client + mapper.
+- :func:`push_open_gaps` / :func:`sync_report` — batch wrappers over a
+  :class:`GapAnalysisReport`. Used by the CLI and REST endpoints.
+
+v0.5.0 uses the Jira Cloud REST API v3 (``/rest/api/3``). Server-hosted
+Jira is untested; most of the same endpoints exist but the workflow
+configuration + auth story diverge. File an issue if you need Server
+support.
+"""
+
+from evidentia_integrations.jira.client import (
+    JiraApiError,
+    JiraClient,
+    JiraIssue,
+)
+from evidentia_integrations.jira.config import JiraConfig
+from evidentia_integrations.jira.mapper import (
+    GAP_STATUS_TO_JIRA_STATUS,
+    JIRA_STATUS_TO_GAP_STATUS,
+    JiraMappingError,
+    gap_to_create_request,
+    jira_status_to_gap_status,
+)
+from evidentia_integrations.jira.sync import (
+    JiraSyncAction,
+    JiraSyncOutcome,
+    JiraSyncResult,
+    push_gap_to_jira,
+    push_open_gaps,
+    sync_gap_from_jira,
+    sync_report,
+)
+
+__all__ = [
+    "GAP_STATUS_TO_JIRA_STATUS",
+    "JIRA_STATUS_TO_GAP_STATUS",
+    "JiraApiError",
+    "JiraClient",
+    "JiraConfig",
+    "JiraIssue",
+    "JiraMappingError",
+    "JiraSyncAction",
+    "JiraSyncOutcome",
+    "JiraSyncResult",
+    "gap_to_create_request",
+    "jira_status_to_gap_status",
+    "push_gap_to_jira",
+    "push_open_gaps",
+    "sync_gap_from_jira",
+    "sync_report",
+]

evidentia_integrations-0.6.0/src/evidentia_integrations/jira/client.py

@@ -0,0 +1,288 @@
+"""httpx-based Jira Cloud REST client.
+
+We use ``httpx`` directly rather than the official ``jira`` PyPI SDK to
+keep the dependency footprint small (Pillow, defusedxml, keyring get
+pulled in otherwise) and because our three use cases — create issue,
+get issue, transition issue — are well within REST reach.
+
+All methods are synchronous for v0.5.0. An async variant lands in v0.5.1
+alongside the gap-batch-push UI flow (generates one issue per gap with
+progress feedback — SSE-style on the GUI path).
+
+**Secret handling.** The ``api_token`` from :class:`JiraConfig` is sent
+as HTTP basic-auth's password field, never logged, never returned in
+any method's output. Exceptions carry the HTTP status code + the Jira
+``errorMessages`` array but never echo the outbound headers.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from evidentia_integrations.jira.config import JiraConfig
+
+logger = logging.getLogger(__name__)
+
+
+class JiraApiError(Exception):
+    """Raised when the Jira REST API returns a non-2xx response.
+
+    Carries the HTTP status code and the ``errorMessages`` array (or a
+    raw body excerpt if Jira returned something unexpected). Never
+    carries request headers — avoids accidentally leaking the
+    Authorization value into a log aggregator.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        errors: list[str] | None = None,
+        body_excerpt: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.errors = errors or []
+        self.body_excerpt = body_excerpt
+        detail = f"[HTTP {status_code}] {message}"
+        if errors:
+            detail += f" -- {'; '.join(errors)}"
+        super().__init__(detail)
+
+
+class JiraIssue(BaseModel):
+    """Typed Jira issue — narrowed to the fields Evidentia cares about."""
+
+    model_config = ConfigDict(extra="allow")
+
+    key: str = Field(description="Issue key, e.g. 'SEC-42'.")
+    id: str = Field(description="Internal numeric id.")
+    summary: str = Field(description="Issue summary.")
+    status_name: str = Field(
+        description="Current workflow status name, e.g. 'To Do', 'In Progress', 'Done'.",
+    )
+    status_category: str = Field(
+        description="Jira status category: 'new', 'indeterminate', 'done', 'undefined'.",
+    )
+    url: str = Field(description="Public issue URL for browser access.")
+
+
+class JiraClient:
+    """Thin Jira Cloud REST v3 client.
+
+    Usage::
+
+        cfg = JiraConfig.from_env()
+        client = JiraClient(cfg)
+        issue = client.create_issue(summary="...", description="...")
+        remote = client.get_issue(issue.key)
+        client.transition_issue(issue.key, target_status="Done")
+    """
+
+    def __init__(
+        self,
+        config: JiraConfig,
+        *,
+        http: httpx.Client | None = None,
+    ) -> None:
+        """Build a client.
+
+        Parameters
+        ----------
+        config
+            Validated :class:`JiraConfig`.
+        http
+            Optional pre-built httpx client — tests inject one backed by
+            ``httpx.MockTransport`` so they don't make network calls.
+        """
+        self._config = config
+        basic = base64.b64encode(
+            f"{config.email}:{config.api_token}".encode()
+        ).decode("ascii")
+        self._http = http or httpx.Client(
+            base_url=config.base_url,
+            headers={
+                "Authorization": f"Basic {basic}",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            timeout=config.timeout_seconds,
+        )
+
+    @property
+    def config(self) -> JiraConfig:
+        """Expose the config for callers (tests, CLI, etc.)."""
+        return self._config
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> JiraClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    # ── Low-level request ───────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Issue a request + raise :class:`JiraApiError` on non-2xx."""
+        try:
+            response = self._http.request(
+                method, path, json=json, params=params
+            )
+        except httpx.HTTPError as e:
+            raise JiraApiError(
+                f"Jira request failed: {e}", status_code=0
+            ) from e
+
+        if response.status_code == 204:
+            return {}
+
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+
+        if not 200 <= response.status_code < 300:
+            errors: list[str] = []
+            if isinstance(body, dict):
+                errors = list(body.get("errorMessages", []))
+                error_field = body.get("errors")
+                if isinstance(error_field, dict):
+                    errors.extend(f"{k}: {v}" for k, v in error_field.items())
+            excerpt = (
+                response.text[:200] + ("..." if len(response.text) > 200 else "")
+                if not errors
+                else None
+            )
+            raise JiraApiError(
+                f"{method.upper()} {path}",
+                status_code=response.status_code,
+                errors=errors,
+                body_excerpt=excerpt,
+            )
+
+        return body if isinstance(body, dict) else {}
+
+    # ── High-level operations ───────────────────────────────────────
+
+    def test_connection(self) -> dict[str, str]:
+        """Verify credentials + project access.
+
+        Returns the authenticated user's display name + the project
+        name. Raises :class:`JiraApiError` if either call fails.
+        """
+        me = self._request("GET", "/rest/api/3/myself")
+        project = self._request(
+            "GET", f"/rest/api/3/project/{self._config.project_key}"
+        )
+        return {
+            "user": str(me.get("displayName") or me.get("emailAddress") or "unknown"),
+            "project_key": self._config.project_key,
+            "project_name": str(project.get("name") or ""),
+            "base_url": self._config.base_url,
+        }
+
+    def create_issue(
+        self,
+        *,
+        summary: str,
+        description: str,
+        labels: list[str] | None = None,
+        extra_fields: dict[str, Any] | None = None,
+    ) -> JiraIssue:
+        """Create a new issue in the configured project.
+
+        ``description`` uses Jira's Atlassian Document Format (ADF) — we
+        wrap a plain-text paragraph automatically. Callers who want
+        richer formatting pass the ADF dict via ``extra_fields``.
+        """
+        adf_description: dict[str, Any] = {
+            "type": "doc",
+            "version": 1,
+            "content": [
+                {
+                    "type": "paragraph",
+                    "content": [{"type": "text", "text": description}],
+                }
+            ],
+        }
+        fields: dict[str, Any] = {
+            "project": {"key": self._config.project_key},
+            "issuetype": {"name": self._config.issue_type},
+            "summary": summary,
+            "description": adf_description,
+            "labels": labels or [],
+        }
+        if extra_fields:
+            fields.update(extra_fields)
+        result = self._request("POST", "/rest/api/3/issue", json={"fields": fields})
+        key = str(result["key"])
+        return self.get_issue(key)
+
+    def get_issue(self, key: str) -> JiraIssue:
+        """Fetch a single issue by key."""
+        body = self._request(
+            "GET",
+            f"/rest/api/3/issue/{key}",
+            params={"fields": "summary,status"},
+        )
+        fields = body.get("fields") or {}
+        status = fields.get("status") or {}
+        status_name = str(status.get("name") or "unknown")
+        status_category = str(
+            (status.get("statusCategory") or {}).get("key") or "undefined"
+        )
+        return JiraIssue(
+            key=str(body["key"]),
+            id=str(body["id"]),
+            summary=str(fields.get("summary") or ""),
+            status_name=status_name,
+            status_category=status_category,
+            url=f"{self._config.base_url}/browse/{body['key']}",
+        )
+
+    def list_transitions(self, key: str) -> list[dict[str, Any]]:
+        """Return the transitions currently available on this issue."""
+        body = self._request("GET", f"/rest/api/3/issue/{key}/transitions")
+        transitions = body.get("transitions", [])
+        return [t for t in transitions if isinstance(t, dict)]
+
+    def transition_issue(self, key: str, *, target_status: str) -> None:
+        """Transition the issue to a target workflow status by name.
+
+        Looks up the available transitions for this issue, finds one
+        whose ``to.name`` matches ``target_status`` case-insensitively,
+        and POSTs to ``/transitions`` with its id. Raises
+        :class:`JiraApiError` if no matching transition exists (e.g.
+        the workflow doesn't allow that move from the current state).
+        """
+        target_lower = target_status.lower()
+        for tr in self.list_transitions(key):
+            to_block = tr.get("to") or {}
+            if str(to_block.get("name", "")).lower() == target_lower:
+                self._request(
+                    "POST",
+                    f"/rest/api/3/issue/{key}/transitions",
+                    json={"transition": {"id": str(tr["id"])}},
+                )
+                return
+        raise JiraApiError(
+            f"No transition to status {target_status!r} available from this issue's "
+            f"current state",
+            status_code=409,
+        )

evidentia_integrations-0.6.0/src/evidentia_integrations/jira/config.py

@@ -0,0 +1,122 @@
+"""Typed Jira client configuration.
+
+Mirrors the minimal subset of Jira configuration we need for gap-push +
+status-sync workflows. Secrets come from environment variables; the
+config object exists to centralize URL / project / mapping settings
+that are fine to commit to ``evidentia.yaml``.
+
+Env vars (resolved at :meth:`JiraConfig.from_env`):
+
+- ``JIRA_BASE_URL``       — e.g. ``https://acme.atlassian.net``
+- ``JIRA_EMAIL``          — the API user's email (basic-auth username)
+- ``JIRA_API_TOKEN``      — the API user's token (basic-auth password).
+  Never logged; never returned in any Evidentia API response.
+- ``JIRA_PROJECT_KEY``    — e.g. ``SEC`` or ``COMPLIANCE``.
+- ``JIRA_ISSUE_TYPE``     — default ``Task``; commonly ``Task`` / ``Story`` /
+  ``Bug`` depending on org conventions.
+
+CLI / API callers that need to override any of these pass kwargs to
+:meth:`JiraConfig.from_env`.
+"""
+
+from __future__ import annotations
+
+import os
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class JiraConfig(BaseModel):
+    """Typed Jira client configuration.
+
+    The ``api_token`` field is stored on the in-memory instance so the
+    client can attach it to outbound requests, but Pydantic's
+    ``model_dump`` / ``model_dump_json`` never serialize it — it's marked
+    ``exclude=True`` so ``JiraConfig(...).model_dump()`` returns only the
+    safe, committable subset.
+    """
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    base_url: str = Field(
+        description=(
+            "Jira base URL, e.g. 'https://acme.atlassian.net'. No trailing slash."
+        ),
+    )
+    email: str = Field(description="Jira user email (basic-auth username).")
+    api_token: str = Field(
+        exclude=True,
+        description=(
+            "Jira API token (basic-auth password). Excluded from model_dump() "
+            "output so it never accidentally lands in a log or API response."
+        ),
+    )
+    project_key: str = Field(
+        description="Jira project key (all caps), e.g. 'SEC', 'COMPLIANCE'.",
+    )
+    issue_type: str = Field(
+        default="Task",
+        description="Jira issue type to create — Task / Story / Bug / etc.",
+    )
+    timeout_seconds: float = Field(
+        default=20.0,
+        gt=0,
+        description="httpx per-request timeout.",
+    )
+
+    @field_validator("base_url")
+    @classmethod
+    def _strip_trailing_slash(cls, v: str) -> str:
+        return v.rstrip("/")
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        base_url: str | None = None,
+        email: str | None = None,
+        api_token: str | None = None,
+        project_key: str | None = None,
+        issue_type: str | None = None,
+    ) -> JiraConfig:
+        """Build a :class:`JiraConfig` from env vars + optional overrides.
+
+        Raises :class:`ValueError` listing every missing required field
+        so the CLI can print a single actionable error message instead
+        of a sequence of single-missing-var complaints.
+        """
+        resolved_url = base_url or os.environ.get("JIRA_BASE_URL")
+        resolved_email = email or os.environ.get("JIRA_EMAIL")
+        resolved_token = api_token or os.environ.get("JIRA_API_TOKEN")
+        resolved_project = project_key or os.environ.get("JIRA_PROJECT_KEY")
+        resolved_type = (
+            issue_type or os.environ.get("JIRA_ISSUE_TYPE") or "Task"
+        )
+
+        missing: list[str] = []
+        if not resolved_url:
+            missing.append("JIRA_BASE_URL")
+        if not resolved_email:
+            missing.append("JIRA_EMAIL")
+        if not resolved_token:
+            missing.append("JIRA_API_TOKEN")
+        if not resolved_project:
+            missing.append("JIRA_PROJECT_KEY")
+
+        if missing:
+            raise ValueError(
+                "Jira is not configured. Set these environment variables: "
+                + ", ".join(missing)
+                + ". See docs/integrations/jira.md."
+            )
+
+        # At this point mypy knows the optionals are populated, but the
+        # type checker can't narrow through the `missing` list branch.
+        assert resolved_url and resolved_email and resolved_token and resolved_project
+        return cls(
+            base_url=resolved_url,
+            email=resolved_email,
+            api_token=resolved_token,
+            project_key=resolved_project,
+            issue_type=resolved_type,
+        )

evidentia_integrations-0.6.0/src/evidentia_integrations/jira/mapper.py

@@ -0,0 +1,170 @@
+"""Pure-functional mapping between Evidentia gaps and Jira issues.
+
+Extracted from :mod:`evidentia_integrations.jira.client` so these
+translations are easy to unit-test without HTTP mocking. The live
+client composes these with REST calls.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from evidentia_core.models.gap import ControlGap, GapSeverity, GapStatus
+
+
+class JiraMappingError(Exception):
+    """Raised when a gap <-> Jira field translation fails validation."""
+
+
+# ── Status mapping ───────────────────────────────────────────────────────
+
+#: GapStatus -> Jira workflow status name (case-insensitive match on sync).
+#: Accepted / Not-applicable map to ``Won't Do`` since Jira's default
+#: workflow doesn't have a dedicated "accepted" transition — they're both
+#: "won't remediate".
+GAP_STATUS_TO_JIRA_STATUS: Final[dict[GapStatus, str]] = {
+    GapStatus.OPEN: "To Do",
+    GapStatus.IN_PROGRESS: "In Progress",
+    GapStatus.REMEDIATED: "Done",
+    GapStatus.ACCEPTED: "Won't Do",
+    GapStatus.NOT_APPLICABLE: "Won't Do",
+}
+
+#: Reverse mapping — Jira status (lowercased) -> GapStatus. Covers the
+#: default Jira Cloud workflow names + a few common customizations
+#: ("Closed", "Resolved") that teams often use.
+JIRA_STATUS_TO_GAP_STATUS: Final[dict[str, GapStatus]] = {
+    "to do": GapStatus.OPEN,
+    "backlog": GapStatus.OPEN,
+    "open": GapStatus.OPEN,
+    "reopened": GapStatus.OPEN,
+    "in progress": GapStatus.IN_PROGRESS,
+    "in review": GapStatus.IN_PROGRESS,
+    "blocked": GapStatus.IN_PROGRESS,
+    "done": GapStatus.REMEDIATED,
+    "resolved": GapStatus.REMEDIATED,
+    "closed": GapStatus.REMEDIATED,
+    "complete": GapStatus.REMEDIATED,
+    "completed": GapStatus.REMEDIATED,
+    "won't do": GapStatus.ACCEPTED,
+    "won't fix": GapStatus.ACCEPTED,
+    "wontfix": GapStatus.ACCEPTED,
+    "cannot reproduce": GapStatus.ACCEPTED,
+    "declined": GapStatus.ACCEPTED,
+}
+
+
+# Severity -> Jira priority name. Jira's default priorities are
+# "Highest / High / Medium / Low / Lowest". If a project customizes
+# priorities the mapping can be overridden at :class:`JiraConfig`
+# level in v0.5.1 — for now, most out-of-box projects accept these.
+_SEVERITY_TO_PRIORITY: Final[dict[GapSeverity, str]] = {
+    GapSeverity.CRITICAL: "Highest",
+    GapSeverity.HIGH: "High",
+    GapSeverity.MEDIUM: "Medium",
+    GapSeverity.LOW: "Low",
+    GapSeverity.INFORMATIONAL: "Lowest",
+}
+
+
+def jira_status_to_gap_status(jira_status_name: str) -> GapStatus | None:
+    """Return the :class:`GapStatus` corresponding to a Jira status name.
+
+    Case-insensitive. Returns ``None`` for unknown statuses so callers
+    can decide how to handle unfamiliar workflow states (log + skip,
+    surface as an error, or prompt the user to extend the mapping).
+    """
+    return JIRA_STATUS_TO_GAP_STATUS.get(jira_status_name.strip().lower())
+
+
+# ── Issue-creation payload ───────────────────────────────────────────────
+
+
+def gap_to_create_request(gap: ControlGap) -> dict[str, object]:
+    """Build the kwargs for :meth:`JiraClient.create_issue` from a gap.
+
+    Produces a structured body with:
+      - ``summary``: ``"[{framework}] {control_id}: {control_title}"``
+      - ``description``: prose summary (severity, effort, gap description,
+        remediation guidance, cross-framework impact)
+      - ``labels``: the framework id + ``evidentia`` + severity
+      - ``extra_fields``: ``priority`` from gap severity.
+    """
+    if not gap.framework or not gap.control_id:
+        raise JiraMappingError(
+            "Gap is missing framework/control_id; cannot push to Jira."
+        )
+
+    summary = f"[{gap.framework}] {gap.control_id}: {gap.control_title}"
+    summary = summary[:250]  # Jira cap is ~255 — stay conservative.
+
+    lines: list[str] = [
+        f"Control: {gap.framework}:{gap.control_id} — {gap.control_title}",
+        f"Severity: {_enum_value(gap.gap_severity)}",
+        f"Effort: {_enum_value(gap.implementation_effort).replace('_', ' ')}",
+        f"Priority score: {gap.priority_score:.2f}",
+        "",
+        "Gap:",
+        gap.gap_description or "(no description)",
+        "",
+        "Remediation guidance:",
+        gap.remediation_guidance or "(no guidance)",
+    ]
+    if gap.cross_framework_value:
+        lines.extend(
+            [
+                "",
+                "Cross-framework impact (closing this gap also satisfies):",
+                *(f"  - {cf}" for cf in gap.cross_framework_value),
+            ]
+        )
+    if gap.equivalent_controls_in_inventory:
+        lines.extend(
+            [
+                "",
+                "Related controls in inventory:",
+                *(f"  - {c}" for c in gap.equivalent_controls_in_inventory),
+            ]
+        )
+    lines.extend(
+        [
+            "",
+            f"Tracked by Evidentia gap id: {gap.id}",
+        ]
+    )
+
+    severity_str = _enum_value(gap.gap_severity)
+    labels = [
+        "evidentia",
+        gap.framework,
+        f"severity-{severity_str}",
+        f"effort-{_enum_value(gap.implementation_effort)}",
+    ]
+
+    priority_name = _SEVERITY_TO_PRIORITY.get(
+        gap.gap_severity
+        if isinstance(gap.gap_severity, GapSeverity)
+        else GapSeverity(gap.gap_severity)  # type: ignore[arg-type]
+    )
+
+    extra_fields: dict[str, object] = {}
+    if priority_name:
+        extra_fields["priority"] = {"name": priority_name}
+
+    return {
+        "summary": summary,
+        "description": "\n".join(lines),
+        "labels": labels,
+        "extra_fields": extra_fields,
+    }
+
+
+def _enum_value(value: object) -> str:
+    """Return the ``.value`` of an enum, or the string form otherwise.
+
+    Evidentia's Pydantic models use ``use_enum_values=True`` which
+    means loaded-from-JSON instances carry strings, while in-memory
+    instances carry the enum itself. Normalizing here lets the mapper
+    work identically on both paths.
+    """
+    return value.value if hasattr(value, "value") else str(value)

evidentia_integrations-0.6.0/src/evidentia_integrations/jira/sync.py

@@ -0,0 +1,358 @@
+"""Gap-to-Jira push + sync helpers.
+
+Composes :class:`JiraClient` with the pure-functional mapper in
+:mod:`.mapper` so callers (CLI, API) get a single function that takes
+a gap and does the right thing:
+
+- :func:`push_gap_to_jira` — create a Jira issue for a gap and stamp
+  the returned key onto ``gap.jira_issue_key``.
+- :func:`sync_gap_from_jira` — read the linked Jira issue and update
+  ``gap.status`` if the Jira status maps to a known GapStatus.
+- :func:`push_open_gaps` / :func:`sync_report` — batch wrappers that
+  iterate a :class:`GapAnalysisReport`.
+
+All functions return structured :class:`JiraSyncOutcome` entries so
+CLI / API callers can render per-gap results without a second pass.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from enum import Enum
+
+from evidentia_core.models.gap import (
+    ControlGap,
+    GapAnalysisReport,
+    GapStatus,
+)
+from pydantic import BaseModel, ConfigDict, Field
+
+from evidentia_integrations.jira.client import (
+    JiraApiError,
+    JiraClient,
+    JiraIssue,
+)
+from evidentia_integrations.jira.mapper import (
+    JiraMappingError,
+    gap_to_create_request,
+    jira_status_to_gap_status,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class JiraSyncAction(str, Enum):
+    """What happened to a single gap during a batch push/sync operation."""
+
+    CREATED = "created"
+    UPDATED = "updated"
+    SKIPPED = "skipped"
+    ERRORED = "errored"
+
+
+class JiraSyncOutcome(BaseModel):
+    """One row of a batch push/sync result — one per gap processed."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    gap_id: str
+    control_id: str
+    framework: str
+    action: JiraSyncAction
+    issue_key: str | None = Field(
+        default=None,
+        description=(
+            "Jira issue key after push/sync — populated on CREATED/UPDATED."
+        ),
+    )
+    issue_url: str | None = Field(default=None)
+    detail: str = Field(
+        description=(
+            "Human-readable one-line explanation — rendered verbatim in "
+            "CLI output and GUI toast messages."
+        ),
+    )
+    new_status: GapStatus | None = Field(
+        default=None,
+        description=(
+            "If the gap's status changed during sync, this is the new value. "
+            "Not mirrored for CREATED actions (those don't change status)."
+        ),
+    )
+
+
+class JiraSyncResult(BaseModel):
+    """Aggregate result of a batch push or sync operation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    started_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    outcomes: list[JiraSyncOutcome] = Field(default_factory=list)
+
+    @property
+    def created(self) -> int:
+        return sum(1 for o in self.outcomes if o.action == JiraSyncAction.CREATED)
+
+    @property
+    def updated(self) -> int:
+        return sum(1 for o in self.outcomes if o.action == JiraSyncAction.UPDATED)
+
+    @property
+    def skipped(self) -> int:
+        return sum(1 for o in self.outcomes if o.action == JiraSyncAction.SKIPPED)
+
+    @property
+    def errored(self) -> int:
+        return sum(1 for o in self.outcomes if o.action == JiraSyncAction.ERRORED)
+
+
+# ── Single-gap ────────────────────────────────────────────────────────────
+
+
+def push_gap_to_jira(
+    gap: ControlGap,
+    client: JiraClient,
+    *,
+    force: bool = False,
+) -> JiraSyncOutcome:
+    """Create a Jira issue for a gap.
+
+    If ``gap.jira_issue_key`` is already populated, the function is a
+    no-op (SKIPPED) — unless ``force=True``, in which case a new issue
+    is created regardless. The previous key isn't deleted from Jira;
+    only the Evidentia linkage is overwritten.
+
+    The function mutates ``gap.jira_issue_key`` on success so callers
+    can persist the updated ``GapAnalysisReport`` back to the gap
+    store.
+    """
+    if gap.jira_issue_key and not force:
+        return JiraSyncOutcome(
+            gap_id=gap.id,
+            control_id=gap.control_id,
+            framework=gap.framework,
+            action=JiraSyncAction.SKIPPED,
+            issue_key=gap.jira_issue_key,
+            detail=(
+                f"Already linked to {gap.jira_issue_key}; pass force=True "
+                "to create a new issue anyway."
+            ),
+        )
+
+    try:
+        payload = gap_to_create_request(gap)
+    except JiraMappingError as e:
+        return JiraSyncOutcome(
+            gap_id=gap.id,
+            control_id=gap.control_id,
+            framework=gap.framework,
+            action=JiraSyncAction.ERRORED,
+            detail=f"Mapping error: {e}",
+        )
+
+    try:
+        # gap_to_create_request returns dict[str, object] because the
+        # nested values mix strings + lists + nested dicts. Narrow to the
+        # concrete shapes JiraClient.create_issue expects; the mapper's
+        # unit tests assert these slots hold their expected types.
+        labels_raw = payload["labels"]
+        extras_raw = payload["extra_fields"]
+        labels: list[str] = list(labels_raw) if isinstance(labels_raw, list) else []
+        extras: dict[str, object] = (
+            dict(extras_raw) if isinstance(extras_raw, dict) else {}
+        )
+        issue: JiraIssue = client.create_issue(
+            summary=str(payload["summary"]),
+            description=str(payload["description"]),
+            labels=labels,
+            extra_fields=extras,
+        )
+    except JiraApiError as e:
+        return JiraSyncOutcome(
+            gap_id=gap.id,
+            control_id=gap.control_id,
+            framework=gap.framework,
+            action=JiraSyncAction.ERRORED,
+            detail=f"Jira API error: {e}",
+        )
+
+    gap.jira_issue_key = issue.key
+    return JiraSyncOutcome(
+        gap_id=gap.id,
+        control_id=gap.control_id,
+        framework=gap.framework,
+        action=JiraSyncAction.CREATED,
+        issue_key=issue.key,
+        issue_url=issue.url,
+        detail=f"Created {issue.key}",
+    )
+
+
+def sync_gap_from_jira(
+    gap: ControlGap,
+    client: JiraClient,
+) -> JiraSyncOutcome:
+    """Read ``gap.jira_issue_key``'s status + update the gap if it changed.
+
+    - No-op SKIPPED when ``gap.jira_issue_key`` is blank.
+    - UPDATED when the Jira status maps to a different GapStatus than
+      the gap currently holds.
+    - SKIPPED ("status unchanged") when the mapping matches.
+    - SKIPPED ("unknown Jira status") when Jira's status name isn't in
+      :data:`JIRA_STATUS_TO_GAP_STATUS`.
+    - ERRORED on HTTP / API failures.
+    """
+    if not gap.jira_issue_key:
+        return JiraSyncOutcome(
+            gap_id=gap.id,
+            control_id=gap.control_id,
+            framework=gap.framework,
+            action=JiraSyncAction.SKIPPED,
+            detail="Gap is not linked to a Jira issue yet.",
+        )
+
+    try:
+        issue = client.get_issue(gap.jira_issue_key)
+    except JiraApiError as e:
+        return JiraSyncOutcome(
+            gap_id=gap.id,
+            control_id=gap.control_id,
+            framework=gap.framework,
+            action=JiraSyncAction.ERRORED,
+            issue_key=gap.jira_issue_key,
+            detail=f"Jira API error: {e}",
+        )
+
+    mapped = jira_status_to_gap_status(issue.status_name)
+    if mapped is None:
+        return JiraSyncOutcome(
+            gap_id=gap.id,
+            control_id=gap.control_id,
+            framework=gap.framework,
+            action=JiraSyncAction.SKIPPED,
+            issue_key=issue.key,
+            issue_url=issue.url,
+            detail=(
+                f"Jira status {issue.status_name!r} isn't in the default "
+                "mapping; leaving gap.status unchanged. Add to "
+                "JIRA_STATUS_TO_GAP_STATUS to honor custom workflow names."
+            ),
+        )
+
+    current = _coerce_gap_status(gap.status)
+    if current == mapped:
+        return JiraSyncOutcome(
+            gap_id=gap.id,
+            control_id=gap.control_id,
+            framework=gap.framework,
+            action=JiraSyncAction.SKIPPED,
+            issue_key=issue.key,
+            issue_url=issue.url,
+            detail=f"Status unchanged ({mapped.value}).",
+        )
+
+    gap.status = mapped
+    if mapped == GapStatus.REMEDIATED and gap.remediated_at is None:
+        gap.remediated_at = datetime.now(UTC)
+
+    return JiraSyncOutcome(
+        gap_id=gap.id,
+        control_id=gap.control_id,
+        framework=gap.framework,
+        action=JiraSyncAction.UPDATED,
+        issue_key=issue.key,
+        issue_url=issue.url,
+        new_status=mapped,
+        detail=(
+            f"Updated gap status: {current.value if current else '?'} -> "
+            f"{mapped.value} (Jira: {issue.status_name})"
+        ),
+    )
+
+
+def _coerce_gap_status(value: object) -> GapStatus | None:
+    """Accept enum or string forms. Returns None for unknown strings."""
+    if isinstance(value, GapStatus):
+        return value
+    if isinstance(value, str):
+        try:
+            return GapStatus(value)
+        except ValueError:
+            return None
+    return None
+
+
+# ── Batch ────────────────────────────────────────────────────────────────
+
+
+def push_open_gaps(
+    report: GapAnalysisReport,
+    client: JiraClient,
+    *,
+    severity_filter: set[str] | None = None,
+    max_issues: int | None = None,
+) -> JiraSyncResult:
+    """Push every OPEN gap in a report as a Jira issue.
+
+    Already-linked gaps are skipped. Use ``severity_filter`` to restrict
+    to e.g. ``{"critical", "high"}``; ``max_issues`` caps total creations
+    (safety rail for first-time setup against a big report).
+    """
+    result = JiraSyncResult()
+    created = 0
+
+    for gap in report.gaps:
+        current_status = _coerce_gap_status(gap.status)
+        if current_status not in (GapStatus.OPEN, GapStatus.IN_PROGRESS):
+            continue
+        if severity_filter is not None:
+            severity_str = (
+                gap.gap_severity.value
+                if hasattr(gap.gap_severity, "value")
+                else str(gap.gap_severity)
+            )
+            if severity_str not in severity_filter:
+                continue
+        if max_issues is not None and created >= max_issues:
+            result.outcomes.append(
+                JiraSyncOutcome(
+                    gap_id=gap.id,
+                    control_id=gap.control_id,
+                    framework=gap.framework,
+                    action=JiraSyncAction.SKIPPED,
+                    detail=f"max_issues={max_issues} reached; skipping remaining gaps.",
+                )
+            )
+            continue
+
+        outcome = push_gap_to_jira(gap, client)
+        result.outcomes.append(outcome)
+        if outcome.action == JiraSyncAction.CREATED:
+            created += 1
+
+    return result
+
+
+def sync_report(
+    report: GapAnalysisReport,
+    client: JiraClient,
+) -> JiraSyncResult:
+    """Sync every linked gap's status from Jira."""
+    result = JiraSyncResult()
+    for gap in report.gaps:
+        if not gap.jira_issue_key:
+            continue
+        result.outcomes.append(sync_gap_from_jira(gap, client))
+    return result
+
+
+__all__ = [
+    "JiraSyncAction",
+    "JiraSyncOutcome",
+    "JiraSyncResult",
+    "push_gap_to_jira",
+    "push_open_gaps",
+    "sync_gap_from_jira",
+    "sync_report",
+]