agentic-devtools 0.2.258__py3-none-any.whl → 0.2.259__py3-none-any.whl

agentic_devtools/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.258'
-__version_tuple__ = version_tuple = (0, 2, 258)
+__version__ = version = '0.2.259'
+__version_tuple__ = version_tuple = (0, 2, 259)
 
 __commit_id__ = commit_id = None

agentic_devtools/adapters/__init__.py

@@ -19,10 +19,13 @@ from agentic_devtools.adapters.base import (
     CommentResult,
     IssueAdapter,
     IssueDetail,
+    IssueDetailWithRaw,
     IssueFilters,
     IssueResult,
     IssueSummary,
+    NormalizedIssue,
 )
+from agentic_devtools.adapters.exceptions import AdapterError, AdapterValidationError
 from agentic_devtools.adapters.github_adapter import GitHubIssuesAdapter
 from agentic_devtools.adapters.jira_adapter import JiraAdapter
 from agentic_devtools.adapters.markdown_adapter import MarkdownAdapter
@@ -30,16 +33,20 @@ from agentic_devtools.config import load_platform_config
 from agentic_devtools.tools.jira import JiraConfig
 
 __all__ = [
+    "AdapterError",
+    "AdapterValidationError",
     "Comment",
     "CommentResult",
     "GitHubIssuesAdapter",
     "IssueAdapter",
     "IssueDetail",
+    "IssueDetailWithRaw",
     "IssueFilters",
     "IssueResult",
     "IssueSummary",
     "JiraAdapter",
     "MarkdownAdapter",
+    "NormalizedIssue",
     "get_adapter",
 ]
 

agentic_devtools/adapters/base.py

@@ -2,114 +2,42 @@
 
 Defines the ``IssueAdapter`` ABC that all platform-specific adapters must
 implement, plus the shared ``TypedDict`` result types used across adapters.
+
+Type definitions live in :mod:`agentic_devtools.adapters.types` and are
+re-exported here for backward compatibility.
 """
 
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
 
-from typing_extensions import TypedDict
-
+from agentic_devtools.adapters.types import (
+    Comment,
+    CommentResult,
+    IssueDetail,
+    IssueDetailWithRaw,
+    IssueFilters,
+    IssueResult,
+    IssueSummary,
+    NormalizedIssue,
+    _IssueDetailRequired,
+)
 from agentic_devtools.orchestration.execution.types import JSONValue
 
-# ---------------------------------------------------------------------------
-# Shared result TypedDicts
-# ---------------------------------------------------------------------------
-
-
-class Comment(TypedDict):
-    """A single comment on an issue."""
-
-    comment_id: str
-    body: str
-    created_at: str
-
-
-class IssueResult(TypedDict):
-    """Result of creating an issue."""
-
-    issue_id: str
-    url: str
-
-
-class _IssueDetailRequired(TypedDict, total=True):
-    """Required fields for issue details (private implementation base)."""
-
-    issue_id: str
-    title: str
-    description: str
-    status: str
-    labels: list[str]
-    url: str
-    comments: list[Comment]
-
-
-class IssueDetail(_IssueDetailRequired, total=False):
-    """Full detail of a single issue.
-
-    Required fields (always present):
-        issue_id: Platform-specific unique issue identifier.
-        title: Issue title / summary text.
-        description: Full issue description body.
-        status: Current workflow status (e.g. "open", "in_progress", "closed").
-        labels: List of labels/tags applied to the issue.
-        url: Web URL for the issue on its platform.
-        comments: List of :class:`Comment` objects on this issue.
-
-    Optional normalization fields (present when adapter populates them):
-        issue_type: The issue type classification (e.g. "bug", "story", "task",
-            "epic"). Adapter-specific; no enum enforced.
-            Example: ``"bug"``
-        priority: Priority level as a human-readable string (e.g. "high",
-            "medium", "low", "P1"). Adapter-specific naming.
-            Example: ``"high"``
-        assignees: List of usernames or display names assigned to the issue.
-            An empty list indicates no assignees; key absence means the adapter
-            did not fetch assignee data.
-            Example: ``["alice", "bob"]``
-        custom_fields: Arbitrary key-value mapping of provider-specific custom
-            fields. Values may be nested dicts, lists, or scalar types.
-            Must be JSON-serializable for persistence.
-            Example: ``{"sprint": "Sprint 42", "story_points": 5}``
-        provider: Identifier for the originating platform adapter (e.g.
-            "github", "jira", "markdown"). Useful for downstream normalization.
-            Example: ``"jira"``
-        raw_metadata: Opaque provider-specific metadata preserved verbatim
-            from the API response. Structure varies by adapter; must be
-            JSON-serializable.
-            Example: ``{"api_version": "3", "expand": "changelog"}``
-    """
-
-    issue_type: str
-    priority: str
-    assignees: list[str]
-    custom_fields: dict[str, JSONValue]
-    provider: str
-    raw_metadata: JSONValue
-
-
-class CommentResult(TypedDict):
-    """Result of adding a comment."""
-
-    comment_id: str
-
-
-class IssueSummary(TypedDict):
-    """Summary of an issue for list results."""
-
-    issue_id: str
-    title: str
-    status: str
-    labels: list[str]
-    url: str
-
-
-class IssueFilters(TypedDict, total=False):
-    """Optional filters for listing issues."""
-
-    labels: list[str]
-    state: str
-    assignee: str
+# Re-export all symbols for backward compatibility
+__all__ = [
+    "Comment",
+    "CommentResult",
+    "IssueAdapter",
+    "IssueDetail",
+    "IssueDetailWithRaw",
+    "IssueFilters",
+    "IssueResult",
+    "IssueSummary",
+    "JSONValue",
+    "NormalizedIssue",
+    "_IssueDetailRequired",
+]
 
 
 # ---------------------------------------------------------------------------
@@ -120,7 +48,8 @@ class IssueFilters(TypedDict, total=False):
 class IssueAdapter(ABC):
     """Abstract base class for issue-tracking platform adapters.
 
-    Concrete subclasses must implement all four abstract methods.
+    Concrete subclasses must implement all abstract methods including
+    :meth:`normalize`.
     """
 
     @abstractmethod
@@ -169,3 +98,20 @@ class IssueAdapter(ABC):
         Returns:
             A list of :class:`IssueSummary` items.
         """
+
+    @abstractmethod
+    def normalize(self, issue_detail: IssueDetailWithRaw) -> NormalizedIssue:
+        """Normalize a raw issue detail into a provider-agnostic representation.
+
+        Transforms platform-specific :class:`IssueDetailWithRaw` data into a
+        uniform :class:`NormalizedIssue` instance suitable for downstream
+        consumers (template renderers, spec generators, etc.).
+
+        Args:
+            issue_detail: An :class:`IssueDetailWithRaw` containing the full
+                issue data and an optional raw provider response payload.
+
+        Returns:
+            A :class:`NormalizedIssue` with validated identity fields and
+            coerced optional fields.
+        """

agentic_devtools/adapters/exceptions.py

@@ -0,0 +1,24 @@
+"""Exception hierarchy for issue adapters.
+
+Provides a minimal exception tree for adapter-level errors:
+
+- :class:`AdapterError` — base class for all adapter exceptions.
+- :class:`AdapterValidationError` — raised when identity field validation
+  fails during :class:`~agentic_devtools.adapters.types.NormalizedIssue`
+  construction.
+"""
+
+from __future__ import annotations
+
+
+class AdapterError(Exception):
+    """Base exception for all issue adapter errors."""
+
+
+class AdapterValidationError(AdapterError):
+    """Raised when adapter identity field validation fails.
+
+    Typically triggered during :class:`NormalizedIssue` construction when
+    required identity fields (``issue_id``, ``title``, ``url``, ``provider``)
+    are ``None``, empty, or whitespace-only.
+    """

agentic_devtools/adapters/github_adapter.py

@@ -15,9 +15,11 @@ from agentic_devtools.adapters.base import (
     CommentResult,
     IssueAdapter,
     IssueDetail,
+    IssueDetailWithRaw,
     IssueFilters,
     IssueResult,
     IssueSummary,
+    NormalizedIssue,
 )
 from agentic_devtools.cli.subprocess_utils import run_safe
 
@@ -166,3 +168,10 @@ class GitHubIssuesAdapter(IssueAdapter):
                 )
             )
         return summaries
+
+    def normalize(self, issue_detail: IssueDetailWithRaw) -> NormalizedIssue:
+        """Normalize a GitHub issue detail into a provider-agnostic representation.
+
+        Not yet implemented — tracked in #1774.
+        """
+        raise NotImplementedError("GitHubIssuesAdapter.normalize() is not yet implemented. See #1774.")

agentic_devtools/adapters/jira_adapter.py

@@ -11,9 +11,11 @@ from agentic_devtools.adapters.base import (
     CommentResult,
     IssueAdapter,
     IssueDetail,
+    IssueDetailWithRaw,
     IssueFilters,
     IssueResult,
     IssueSummary,
+    NormalizedIssue,
 )
 from agentic_devtools.tools.jira import JiraConfig
 from agentic_devtools.tools.jira import add_comment as jira_add_comment
@@ -117,3 +119,10 @@ class JiraAdapter(IssueAdapter):
     def list_issues(self, filters: IssueFilters | None = None) -> list[IssueSummary]:
         """Not yet implemented for Jira."""
         raise NotImplementedError("JiraAdapter.list_issues is not yet implemented. Full Jira search is a future issue.")
+
+    def normalize(self, issue_detail: IssueDetailWithRaw) -> NormalizedIssue:
+        """Normalize a Jira issue detail into a provider-agnostic representation.
+
+        Not yet implemented — tracked in #1775.
+        """
+        raise NotImplementedError("JiraAdapter.normalize() is not yet implemented. See #1775.")

agentic_devtools/adapters/markdown_adapter.py

@@ -19,9 +19,11 @@ from agentic_devtools.adapters.base import (
     CommentResult,
     IssueAdapter,
     IssueDetail,
+    IssueDetailWithRaw,
     IssueFilters,
     IssueResult,
     IssueSummary,
+    NormalizedIssue,
 )
 
 _ID_PATTERN = re.compile(r"^\d{3}$")
@@ -284,3 +286,10 @@ class MarkdownAdapter(IssueAdapter):
                 )
             )
         return summaries
+
+    def normalize(self, issue_detail: IssueDetailWithRaw) -> NormalizedIssue:
+        """Normalize a Markdown issue detail into a provider-agnostic representation.
+
+        Not yet implemented — tracked in #1776.
+        """
+        raise NotImplementedError("MarkdownAdapter.normalize() is not yet implemented. See #1776.")

agentic_devtools/adapters/types.py

@@ -0,0 +1,205 @@
+"""Shared type definitions for issue adapters.
+
+Contains all TypedDict result types originally defined in ``base.py``, plus:
+
+- :class:`IssueDetailWithRaw` — extends :class:`IssueDetail` with a ``raw`` field.
+- :class:`NormalizedIssue` — frozen dataclass representing a provider-agnostic
+  normalized issue with identity validation and coercion.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from typing_extensions import TypedDict
+
+from agentic_devtools.adapters.exceptions import AdapterValidationError
+from agentic_devtools.orchestration.execution.types import JSONValue
+
+# ---------------------------------------------------------------------------
+# Shared result TypedDicts (moved from base.py)
+# ---------------------------------------------------------------------------
+
+
+class Comment(TypedDict):
+    """A single comment on an issue."""
+
+    comment_id: str
+    body: str
+    created_at: str
+
+
+class IssueResult(TypedDict):
+    """Result of creating an issue."""
+
+    issue_id: str
+    url: str
+
+
+class _IssueDetailRequired(TypedDict, total=True):
+    """Required fields for issue details (private implementation base)."""
+
+    issue_id: str
+    title: str
+    description: str
+    status: str
+    labels: list[str]
+    url: str
+    comments: list[Comment]
+
+
+class IssueDetail(_IssueDetailRequired, total=False):
+    """Full detail of a single issue.
+
+    Required fields (always present):
+        issue_id: Platform-specific unique issue identifier.
+        title: Issue title / summary text.
+        description: Full issue description body.
+        status: Current workflow status (e.g. "open", "in_progress", "closed").
+        labels: List of labels/tags applied to the issue.
+        url: Web URL for the issue on its platform.
+        comments: List of :class:`Comment` objects on this issue.
+
+    Optional normalization fields (present when adapter populates them):
+        issue_type: The issue type classification (e.g. "bug", "story", "task",
+            "epic"). Adapter-specific; no enum enforced.
+            Example: ``"bug"``
+        priority: Priority level as a human-readable string (e.g. "high",
+            "medium", "low", "P1"). Adapter-specific naming.
+            Example: ``"high"``
+        assignees: List of usernames or display names assigned to the issue.
+            An empty list indicates no assignees; key absence means the adapter
+            did not fetch assignee data.
+            Example: ``["alice", "bob"]``
+        custom_fields: Arbitrary key-value mapping of provider-specific custom
+            fields. Values may be nested dicts, lists, or scalar types.
+            Must be JSON-serializable for persistence.
+            Example: ``{"sprint": "Sprint 42", "story_points": 5}``
+        provider: Identifier for the originating platform adapter (e.g.
+            "github", "jira", "markdown"). Useful for downstream normalization.
+            Example: ``"jira"``
+        raw_metadata: Opaque provider-specific metadata preserved verbatim
+            from the API response. Structure varies by adapter; must be
+            JSON-serializable.
+            Example: ``{"api_version": "3", "expand": "changelog"}``
+    """
+
+    issue_type: str
+    priority: str
+    assignees: list[str]
+    custom_fields: dict[str, JSONValue]
+    provider: str
+    raw_metadata: JSONValue
+
+
+class CommentResult(TypedDict):
+    """Result of adding a comment."""
+
+    comment_id: str
+
+
+class IssueSummary(TypedDict):
+    """Summary of an issue for list results."""
+
+    issue_id: str
+    title: str
+    status: str
+    labels: list[str]
+    url: str
+
+
+class IssueFilters(TypedDict, total=False):
+    """Optional filters for listing issues."""
+
+    labels: list[str]
+    state: str
+    assignee: str
+
+
+# ---------------------------------------------------------------------------
+# Extended TypedDict: IssueDetailWithRaw
+# ---------------------------------------------------------------------------
+
+
+class IssueDetailWithRaw(IssueDetail, total=False):
+    """Issue detail extended with raw provider response data.
+
+    Inherits all fields from :class:`IssueDetail` and optionally adds a
+    ``raw`` dict containing the unmodified provider API response, enabling
+    downstream normalizers to access fields not covered by the base schema.
+    """
+
+    raw: dict[str, Any]
+
+
+# ---------------------------------------------------------------------------
+# Normalized issue dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class NormalizedIssue:
+    """Provider-agnostic normalized representation of an issue.
+
+    All adapters' ``normalize()`` method returns an instance of this class,
+    ensuring a uniform contract for downstream consumers (template renderers,
+    spec generators, etc.).
+
+    Identity fields (``issue_id``, ``title``, ``url``, ``provider``) are
+    validated in ``__post_init__`` as non-empty strings —
+    ``None``, non-string, empty, or whitespace-only values raise
+    :class:`AdapterValidationError`.
+
+    Coercion rules applied in ``__post_init__``:
+        - ``description``: ``None`` → ``""``
+        - ``comments``: ``None`` → ``[]``
+        - ``labels``: non-list → ``[]``
+        - ``status``: ``None`` or non-string → ``"unknown"``; lowercased
+    """
+
+    issue_id: str
+    title: str
+    url: str
+    provider: str
+    description: str
+    status: str
+    labels: list[str] = field(default_factory=list)
+    comments: list[Comment] = field(default_factory=list)
+    created_at: str = ""
+    updated_at: str = ""
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Validate identity fields and coerce optional fields."""
+        # Identity validation
+        for field_name in ("issue_id", "title", "url", "provider"):
+            value = getattr(self, field_name)
+            if not isinstance(value, str) or not value.strip():
+                raise AdapterValidationError(f"NormalizedIssue.{field_name} must be a non-empty string; got {value!r}")
+
+        # Coerce description
+        if getattr(self, "description") is None:
+            object.__setattr__(self, "description", "")
+
+        # Coerce comments then defensive-copy to prevent external mutation
+        comments = getattr(self, "comments")
+        object.__setattr__(self, "comments", [] if comments is None else list(comments))
+
+        # Coerce labels then defensive-copy to prevent external mutation
+        labels = getattr(self, "labels")
+        object.__setattr__(self, "labels", [] if labels is None or not isinstance(labels, list) else list(labels))
+
+        # Coerce status
+        status = getattr(self, "status")
+        if status is None or not isinstance(status, str):
+            object.__setattr__(self, "status", "unknown")
+        else:
+            object.__setattr__(self, "status", status.lower())
+
+        # Defensive-copy raw to prevent external mutation
+        object.__setattr__(self, "raw", dict(getattr(self, "raw")))
+
+    def __hash__(self) -> int:
+        """NormalizedIssue is not hashable due to mutable fields."""
+        raise TypeError(f"unhashable type: '{type(self).__name__}'")

{agentic_devtools-0.2.258.dist-info → agentic_devtools-0.2.259.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-devtools
-Version: 0.2.258
+Version: 0.2.259
 Summary: Agentic devtools integrate Jira, DevOps & more
 Author: ayaiayorg
 License-Expression: MIT

{agentic_devtools-0.2.258.dist-info → agentic_devtools-0.2.259.dist-info}/RECORD

@@ -1,5 +1,5 @@
 agentic_devtools/__init__.py,sha256=J_Zw_vWKghk-cLmqI83hXQmSiS8zMhGIHM5WPLDkZuo,242
-agentic_devtools/_version.py,sha256=SmYZcFFT2gJY8_CzDdkuZh9qlZ9fwKGlzXtJr3cq2KU,524
+agentic_devtools/_version.py,sha256=oYVy2gkppQXpBIPMhcfNgGDqrHlFOJg-qvATCFO1Ccg,524
 agentic_devtools/agdt_gitignore.py,sha256=Jcc9BUiCIqCG9tUuHc5Jua5tPT_QtTnEK6Gr0v_RrKQ,1559
 agentic_devtools/background_tasks.py,sha256=QCiCSTcU8HSFa_g_fa2NWXhhRZU4zo6YgsPSIVVmdOU,16971
 agentic_devtools/config.py,sha256=X6zv8Twviv9LMiV7TYy_6SQeNezJHV8lBNvIxLkOqLY,8049
@@ -14,11 +14,13 @@ agentic_devtools/_bundled_skills/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRk
 agentic_devtools/_bundled_skills/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agentic_devtools/_bundled_skills/prompts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agentic_devtools/_bundled_skills/workflow-analysis/SKILL.md,sha256=imOFULtiGqsFEljGx0ly7_ntnZAmLWuYAF0HL82MIVA,21153
-agentic_devtools/adapters/__init__.py,sha256=ui0EniKozxEilk7URxmfio2SPRbIOpo_Y2jHdVMrn_k,6190
-agentic_devtools/adapters/base.py,sha256=fxi__WxmXdrC6HMTzjGC2fIBGChtGp4LYQXFHLQpImk,5263
-agentic_devtools/adapters/github_adapter.py,sha256=lVvxNoZMazg4uj4R69NSVMmEEKePh4SVc9J9Ve7WeqY,6538
-agentic_devtools/adapters/jira_adapter.py,sha256=vecgx6dbJ-DlggxL2nKzeC6jqEpxEPHDClsJz0HdaoY,4913
-agentic_devtools/adapters/markdown_adapter.py,sha256=4Ib6SNsAufwk4MguAyxDTywCGv1u2kAEZEmd9d0N_mM,11235
+agentic_devtools/adapters/__init__.py,sha256=5Qy6VAi7HjpSbVFUlVTETarv0Gdt7XcO5vY7VgUsSyU,6420
+agentic_devtools/adapters/base.py,sha256=TEOCW79kCN1jBYir7mlShRIxRRv3O6CnqoCHvMDTDPA,3449
+agentic_devtools/adapters/exceptions.py,sha256=SJJz53MjiOk2DWAmddThHvbtk0yfovU5DlyW77su1rA,777
+agentic_devtools/adapters/github_adapter.py,sha256=7IOKiTB1PtwAaLqaoM26pQg0yNThouxTi_-gBUfie4w,6913
+agentic_devtools/adapters/jira_adapter.py,sha256=AYYqtx12fZO44Dk7YfW6Lq_Tk_LHVUn6KN9DDQim1WY,5278
+agentic_devtools/adapters/markdown_adapter.py,sha256=poSKmq0-XBL1-537re6uUdGMzQDt18BEc38M0pBU74I,11608
+agentic_devtools/adapters/types.py,sha256=oXZylcbHdJ-yPeRiIL2yw6pzfrK0-sp0fe7unHaVBZQ,7231
 agentic_devtools/cli/__init__.py,sha256=VgHQrGk0NuMaGMdvooFwz3nGY1NzVi6kX5Fr7wF-Tdw,40
 agentic_devtools/cli/activity_log.py,sha256=Cv-LEF2utB4UqJ4k_UZkbz8uEAnku8XwPt93CSkKTA0,11474
 agentic_devtools/cli/apply_thread_autofix_suggestions.py,sha256=-zQ7oWdNFj_ajuUKXT3nDYUR8YGA6oGEN1bZtjIwcj4,10176
@@ -745,8 +747,8 @@ agentic_devtools/_bundled_skills/prompts/speckit.plan.prompt.md,sha256=IJja5r2Sd
 agentic_devtools/_bundled_skills/prompts/speckit.specify.prompt.md,sha256=eyzE3GRi2hyW30a6xPYOU7q6MJf0skrD-baEGURYqpg,31
 agentic_devtools/_bundled_skills/prompts/speckit.tasks.prompt.md,sha256=iPxXwon5nV6dNcJV8-JoP3PssKUVXctNiG-C9SsRhB8,29
 agentic_devtools/_bundled_skills/prompts/speckit.taskstoissues.prompt.md,sha256=L5Y21PMSoUcPAAdHy2Jnf-wGVdi04jV_pPvyOJZfpm0,37
-agentic_devtools-0.2.258.dist-info/METADATA,sha256=l5tR54p4QS3pHvoBIr_bhc-W71uCat1xXo_I50E4EV4,29707
-agentic_devtools-0.2.258.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-agentic_devtools-0.2.258.dist-info/entry_points.txt,sha256=w34XSOdR4kX3N64ZmSlfcUinrIp_mSXiPfNNew1efzg,10749
-agentic_devtools-0.2.258.dist-info/licenses/LICENSE,sha256=yBEDdICksxhBYLWoERKp9MTqwGnUF6Ryj9BTLwXTc6k,1082
-agentic_devtools-0.2.258.dist-info/RECORD,,
+agentic_devtools-0.2.259.dist-info/METADATA,sha256=UUs-zlNJ_-0uM2dnS_Zsj9sSGMSEI931gMZ2wnj6ZLY,29707
+agentic_devtools-0.2.259.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentic_devtools-0.2.259.dist-info/entry_points.txt,sha256=w34XSOdR4kX3N64ZmSlfcUinrIp_mSXiPfNNew1efzg,10749
+agentic_devtools-0.2.259.dist-info/licenses/LICENSE,sha256=yBEDdICksxhBYLWoERKp9MTqwGnUF6Ryj9BTLwXTc6k,1082
+agentic_devtools-0.2.259.dist-info/RECORD,,