@ngocsangairvds/vsaf 3.1.27 → 3.2.2

package/tools/vds-scripts/jira_orchestrator/src/vds_jira_orchestrator/config.py

@@ -0,0 +1,138 @@
+"""Strongly-typed Jira settings using pydantic-settings (SDK-only)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import AnyHttpUrl, Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+_PROJECT_ROOT = Path(__file__).resolve().parents[3]
+_SCRIPTS_DIR = _PROJECT_ROOT.parent
+
+DEFAULT_ENV_PATHS = (
+    Path.home() / ".vds" / ".env",
+    _SCRIPTS_DIR / ".env",
+)
+
+_REQUIRED_KEYS: tuple[str, ...] = (
+    "VDS_USERNAME",
+    "VDS_PASSWORD",
+    "JIRA_TOKEN",
+)
+
+_OPTIONAL_KEYS: tuple[str, ...] = ("JIRA_BASE_URL",)
+
+
+class SettingsError(RuntimeError):
+    """Raised when the environment configuration cannot be loaded."""
+
+
+class JiraSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=None, env_prefix="", case_sensitive=True, populate_by_name=True)
+
+    username: str | None = Field(default=None, alias="VDS_USERNAME")
+    password: str | None = Field(default=None, alias="VDS_PASSWORD")
+
+    base_url: str = Field(default="http://jira.digital.vn", alias="JIRA_BASE_URL")
+
+    # Optional: PAT/token if available for Jira Server/DC
+    token: str | None = Field(default=None, alias="JIRA_TOKEN")
+
+    def require_basic_or_token(self) -> None:
+        if not ((self.username and self.password) or self.token):
+            raise ValueError("Missing credentials: set VDS_USERNAME/VDS_PASSWORD or JIRA_TOKEN")
+
+    @field_validator("base_url")
+    @classmethod
+    def _validate_base_url(cls, value: str) -> str:
+        AnyHttpUrl(value)
+        return value.rstrip("/")
+
+
+@dataclass(frozen=True)
+class EnvSnapshot:
+    """A snapshot of relevant environment variables."""
+
+    values: Mapping[str, str]
+    source: Path | str | None
+
+
+def _parse_env_file(env_path: Path) -> dict[str, str]:
+    if not env_path.exists():
+        return {}
+
+    result: dict[str, str] = {}
+    for raw_line in env_path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, raw_value = line.split("=", 1)
+        key = key.strip()
+        value = raw_value.strip().strip('"').strip("'")
+        if key:
+            result[key] = value
+    return result
+
+
+def _merge_env_sources(*snapshots: EnvSnapshot) -> dict[str, str]:
+    merged: dict[str, str] = {}
+    for snapshot in snapshots:
+        merged.update(snapshot.values)
+    return merged
+
+
+def _filter_keys(source: Mapping[str, str]) -> dict[str, str]:
+    relevant_keys = set(_REQUIRED_KEYS + _OPTIONAL_KEYS)
+    return {key: value for key, value in source.items() if key in relevant_keys}
+
+
+def _resolve_env_paths(env_path: Path | None) -> Iterable[Path]:
+    if env_path is not None:
+        return (env_path,)
+    return DEFAULT_ENV_PATHS
+
+
+def load_settings(
+    *,
+    env_path: Path | None = None,
+    overrides: Mapping[str, str] | None = None,
+    strict: bool = False,
+) -> JiraSettings:
+    """Load orchestrator settings from the environment and optional .env file."""
+
+    snapshots = []
+    for candidate in _resolve_env_paths(env_path):
+        snapshots.append(
+            EnvSnapshot(
+                values=_filter_keys(_parse_env_file(candidate)), source=candidate if candidate.exists() else None
+            )
+        )
+
+    snapshots.append(EnvSnapshot(values=_filter_keys(os.environ), source="os.environ"))
+
+    if overrides:
+        snapshots.append(EnvSnapshot(values=_filter_keys(overrides), source="overrides"))
+
+    merged = _merge_env_sources(*snapshots)
+
+    try:
+        settings = JiraSettings.model_validate(merged)
+    except Exception as exc:
+        raise SettingsError(str(exc)) from exc
+
+    if strict:
+        try:
+            settings.require_basic_or_token()
+        except ValueError as exc:
+            raise SettingsError(str(exc)) from exc
+
+    return settings
+
+
+__all__ = ["JiraSettings", "SettingsError", "load_settings", "DEFAULT_ENV_PATHS"]

package/tools/vds-scripts/jira_orchestrator/src/vds_jira_orchestrator/errors.py

@@ -0,0 +1,67 @@
+"""Domain errors for Jira adapter (consistent with VDS orchestrators)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class JiraAdapterError(RuntimeError):
+    """Base class for Jira adapter errors."""
+
+    def __init__(self, message: str, *, context: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.context = context or {}
+
+
+class JiraAuthError(JiraAdapterError):
+    """Raised when authentication fails (401/403)."""
+
+    pass
+
+
+class JiraNotFound(JiraAdapterError):
+    """Raised when a resource is not found (404)."""
+
+    pass
+
+
+class JiraRateLimited(JiraAdapterError):
+    """Raised when rate limited by JIRA (429)."""
+
+    def __init__(
+        self, message: str, *, retry_after: float | None = None, context: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(message, context=context)
+        self.retry_after = retry_after
+
+
+class JiraConflictError(JiraAdapterError):
+    """Raised when there's a conflict (409)."""
+
+    pass
+
+
+class JiraResponseError(JiraAdapterError):
+    """Raised for other HTTP errors (4xx/5xx)."""
+
+    def __init__(
+        self, message: str, *, status_code: int | None = None, context: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(message, context=context)
+        self.status_code = status_code
+
+
+class JiraTransportError(JiraAdapterError):
+    """Raised for network/transport issues."""
+
+    pass
+
+
+class JiraRetryError(JiraAdapterError):
+    """Raised when retry attempts are exhausted."""
+
+    def __init__(
+        self, message: str, *, attempts: int | None = None, context: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(message, context=context)
+        self.attempts = attempts

package/tools/vds-scripts/jira_orchestrator/src/vds_jira_orchestrator/reporting.py

@@ -0,0 +1,65 @@
+"""Run reporting utilities for the Jira orchestrator."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+TIMESTAMP_FMT = "%Y-%m-%dT%H-%M-%SZ"
+
+
+@dataclass(slots=True)
+class RunSummary:
+    command: str
+    args: list[str]
+    exit_code: int
+    duration_ms: int
+    started_at: datetime
+    finished_at: datetime
+
+    @property
+    def success(self) -> bool:
+        return self.exit_code == 0
+
+
+def _ensure_directory(base: Path, timestamp: datetime) -> Path:
+    day_dir = base / str(timestamp.year) / f"{timestamp.month:02d}" / f"{timestamp.day:02d}"
+    day_dir.mkdir(parents=True, exist_ok=True)
+    return day_dir
+
+
+def write_reports(summary: RunSummary, *, base_dir: Path, include_markdown: bool = True) -> Path:
+    """Persist JSON (and optional Markdown) reports and return JSON path."""
+    timestamp = summary.finished_at.astimezone(UTC)
+    directory = _ensure_directory(base_dir, timestamp)
+    slug = f"{timestamp.strftime(TIMESTAMP_FMT)}_{summary.command}"
+
+    json_path = directory / f"{slug}.json"
+    json_payload = {
+        "command": summary.command,
+        "args": summary.args,
+        "exit_code": summary.exit_code,
+        "duration_ms": summary.duration_ms,
+        "started_at": summary.started_at.astimezone(UTC).isoformat().replace("+00:00", "Z"),
+        "finished_at": summary.finished_at.astimezone(UTC).isoformat().replace("+00:00", "Z"),
+        "success": summary.success,
+    }
+    json_path.write_text(json.dumps(json_payload, indent=2, sort_keys=True))
+
+    if include_markdown:
+        md_path = directory / f"{slug}.md"
+        status = "✅ Success" if summary.success else "❌ Failure"
+        md_lines = [
+            f"# Jira Run Report — {summary.command}",
+            "",
+            f"- **Status**: {status} (exit code {summary.exit_code})",
+            f"- **Duration**: {summary.duration_ms} ms",
+            f"- **Started**: {json_payload['started_at']}",
+            f"- **Finished**: {json_payload['finished_at']}",
+        ]
+        if summary.args:
+            md_lines.append(f"- **Arguments**: {' '.join(summary.args)}")
+        md_path.write_text("\n".join(md_lines) + "\n")
+
+    return json_path

package/tools/vds-scripts/jira_orchestrator/tests/__init__.py

@@ -0,0 +1 @@
+"""Test configuration and fixtures for Jira orchestrator tests."""

package/tools/vds-scripts/jira_orchestrator/tests/conftest.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from vds_jira_orchestrator.config import JiraSettings
+
+
+def clear_runtime_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Clear runtime environment variables for testing."""
+    for key in (
+        "VDS_USERNAME",
+        "VDS_PASSWORD",
+        "JIRA_TOKEN",
+        "JIRA_BASE_URL",
+    ):
+        monkeypatch.delenv(key, raising=False)
+
+
+def write_env(tmp_path: Path, content: str) -> Path:
+    """Write a temporary .env file for testing."""
+    env_path = tmp_path / ".env"
+    env_path.write_text(content)
+    return env_path
+
+
+@pytest.fixture
+def mock_jira_settings() -> JiraSettings:
+    """Create mock Jira settings for testing."""
+    return JiraSettings(
+        VDS_USERNAME="test_user",
+        VDS_PASSWORD="test_pass",
+        JIRA_TOKEN="test_token",
+        JIRA_BASE_URL="https://jira.test.com",
+    )
+
+
+@pytest.fixture
+def sample_issue_response() -> dict[str, object]:
+    """Sample Jira issue response."""
+    return {
+        "id": "10001",
+        "key": "TEST-123",
+        "fields": {
+            "summary": "Test Issue",
+            "description": "This is a test issue",
+            "status": {"name": "Open"},
+            "priority": {"name": "Medium"},
+            "issuetype": {"name": "Task"},
+            "project": {"key": "TEST", "name": "Test Project"},
+        },
+    }
+
+
+@pytest.fixture
+def sample_project_response() -> dict[str, object]:
+    """Sample Jira project response."""
+    return {
+        "id": "10000",
+        "key": "TEST",
+        "name": "Test Project",
+        "description": "A test project",
+        "projectTypeKey": "software",
+        "lead": {"displayName": "Test User"},
+    }
+
+
+@pytest.fixture
+def sample_search_results() -> dict[str, object]:
+    """Sample Jira search results."""
+    return {
+        "startAt": 0,
+        "maxResults": 50,
+        "total": 1,
+        "issues": [
+            {
+                "id": "10001",
+                "key": "TEST-123",
+                "fields": {
+                    "summary": "Test Issue",
+                    "status": {"name": "Open"},
+                    "priority": {"name": "Medium"},
+                },
+            }
+        ],
+    }

package/tools/vds-scripts/jira_orchestrator/tests/test_adapter_agile_list_payloads.py

@@ -0,0 +1,54 @@
+from unittest.mock import Mock, patch
+
+from vds_jira_orchestrator.adapter import JiraAdapter
+
+
+@patch("vds_jira_orchestrator.adapter.Jira")
+def test_get_all_agile_boards_unwraps_values_list(mock_jira: Mock) -> None:
+    client = Mock()
+    client.get_all_agile_boards.return_value = {
+        "maxResults": 50,
+        "startAt": 0,
+        "isLast": True,
+        "values": [{"id": 1, "name": "NTTC Scrum Board"}],
+    }
+    mock_jira.return_value = client
+
+    adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+    result = adapter.get_all_agile_boards(project_key="NTTC", limit=50)
+
+    assert result == [{"id": 1, "name": "NTTC Scrum Board"}]
+
+
+@patch("vds_jira_orchestrator.adapter.Jira")
+def test_get_issues_for_board_unwraps_issues_list(mock_jira: Mock) -> None:
+    client = Mock()
+    client.get_issues_for_board.return_value = {
+        "startAt": 0,
+        "maxResults": 50,
+        "total": 1,
+        "issues": [{"key": "NTTC-5705"}],
+    }
+    mock_jira.return_value = client
+
+    adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+    result = adapter.get_issues_for_board(1)
+
+    assert result == [{"key": "NTTC-5705"}]
+
+
+@patch("vds_jira_orchestrator.adapter.Jira")
+def test_get_all_sprints_from_board_unwraps_values_list(mock_jira: Mock) -> None:
+    client = Mock()
+    client.get_all_sprints_from_board.return_value = {
+        "maxResults": 50,
+        "startAt": 0,
+        "isLast": True,
+        "values": [{"id": 101, "name": "Sprint 1"}],
+    }
+    mock_jira.return_value = client
+
+    adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+    result = adapter.get_all_sprints_from_board(1)
+
+    assert result == [{"id": 101, "name": "Sprint 1"}]

package/tools/vds-scripts/jira_orchestrator/tests/test_adapter_bulk_operations.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from vds_jira_orchestrator.adapter import JiraAdapter, JiraAdapterError
+
+
+@pytest.fixture
+def mock_adapter() -> JiraAdapter:
+    """Fixture for a JiraAdapter."""
+    with patch("vds_jira_orchestrator.adapter.Jira") as mock_jira_class:
+        mock_client = MagicMock()
+        mock_jira_class.return_value = mock_client
+        adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+        adapter._client = mock_client
+        return adapter
+
+
+def test_bulk_update_issue_field_calls_client(mock_adapter: JiraAdapter) -> None:
+    """Test that bulk_update_issue_field calls the SDK client with correct parameters."""
+    mock_adapter._client.bulk_update_issue_field.return_value = {"updated": 2, "errors": []}
+    result = mock_adapter.bulk_update_issue_field(key_list=["TEST-1", "TEST-2"], fields="*all")
+    mock_adapter._client.bulk_update_issue_field.assert_called_once_with(["TEST-1", "TEST-2"], fields="*all")
+    assert result["updated"] == 2
+
+
+def test_bulk_update_issue_field_with_fields(mock_adapter: JiraAdapter) -> None:
+    """Test bulk_update_issue_field with specific fields."""
+    mock_adapter._client.bulk_update_issue_field.return_value = {"updated": 1, "errors": []}
+    fields_json = '{"summary": "Updated summary"}'
+    result = mock_adapter.bulk_update_issue_field(key_list=["TEST-1"], fields=fields_json)
+    mock_adapter._client.bulk_update_issue_field.assert_called_once_with(["TEST-1"], fields=fields_json)
+    assert result["updated"] == 1
+
+
+def test_bulk_update_issue_field_handles_error(mock_adapter: JiraAdapter) -> None:
+    """Test that bulk_update_issue_field handles errors from the SDK client."""
+    mock_adapter._client.bulk_update_issue_field.side_effect = Exception("API Error")
+    with pytest.raises(JiraAdapterError, match="API Error"):
+        mock_adapter.bulk_update_issue_field(key_list=["TEST-1"], fields="*all")
+
+
+def test_issue_field_value_append_calls_client(mock_adapter: JiraAdapter) -> None:
+    """Test that issue_field_value_append calls the SDK client with correct parameters."""
+    mock_adapter._client.issue_field_value_append.return_value = {"id": "10000", "value": "appended"}
+    value_dict = {"name": "test-value"}
+    result = mock_adapter.issue_field_value_append(issue_id_or_key="TEST-1", field="customfield_10000", value=value_dict)
+    mock_adapter._client.issue_field_value_append.assert_called_once_with("TEST-1", "customfield_10000", value_dict, notify_users=True)
+    assert result["id"] == "10000"
+
+
+def test_issue_field_value_append_with_notify_false(mock_adapter: JiraAdapter) -> None:
+    """Test issue_field_value_append with notify_users=False."""
+    mock_adapter._client.issue_field_value_append.return_value = {"id": "10001", "value": "appended"}
+    value_dict = {"name": "another-value"}
+    result = mock_adapter.issue_field_value_append(
+        issue_id_or_key="TEST-2", field="customfield_10000", value=value_dict, notify_users=False
+    )
+    mock_adapter._client.issue_field_value_append.assert_called_once_with("TEST-2", "customfield_10000", value_dict, notify_users=False)
+    assert result["id"] == "10001"
+
+
+def test_issue_field_value_append_handles_error(mock_adapter: JiraAdapter) -> None:
+    """Test that issue_field_value_append handles errors from the SDK client."""
+    mock_adapter._client.issue_field_value_append.side_effect = Exception("API Error")
+    with pytest.raises(JiraAdapterError, match="API Error"):
+        mock_adapter.issue_field_value_append(issue_id_or_key="TEST-1", field="customfield_10000", value={"name": "value"})
+

package/tools/vds-scripts/jira_orchestrator/tests/test_adapter_components.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from vds_jira_orchestrator.adapter import JiraAdapter
+
+
+@patch("vds_jira_orchestrator.adapter.Jira")
+def test_get_component_calls_sdk(mock_jira: MagicMock) -> None:
+    client = MagicMock()
+    client.component.return_value = {"id": 10, "name": "Comp"}
+    mock_jira.return_value = client
+
+    adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+    payload = adapter.get_component(10)
+
+    client.component.assert_called_once_with(10)
+    assert payload["id"] == 10
+
+
+@patch("vds_jira_orchestrator.adapter.Jira")
+def test_create_component_calls_sdk(mock_jira: MagicMock) -> None:
+    client = MagicMock()
+    client.create_component.return_value = {"id": 11}
+    mock_jira.return_value = client
+    adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+
+    payload = {"name": "NewComp", "projectKey": "NTTC"}
+    result = adapter.create_component(payload)
+
+    client.create_component.assert_called_once_with(payload)
+    assert result["id"] == 11
+
+
+@patch("vds_jira_orchestrator.adapter.Jira")
+def test_update_component_calls_sdk(mock_jira: MagicMock) -> None:
+    client = MagicMock()
+    client.update_component.return_value = {"id": 12, "name": "Updated"}
+    mock_jira.return_value = client
+    adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+
+    result = adapter.update_component(12, {"name": "Updated"})
+
+    client.update_component.assert_called_once_with(12, {"name": "Updated"})
+    assert result["name"] == "Updated"
+
+
+@patch("vds_jira_orchestrator.adapter.Jira")
+def test_delete_component_calls_sdk(mock_jira: MagicMock) -> None:
+    client = MagicMock()
+    mock_jira.return_value = client
+    adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+
+    adapter.delete_component("13")
+
+    client.delete_component.assert_called_once_with("13")
+

package/tools/vds-scripts/jira_orchestrator/tests/test_adapter_createmeta.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import requests
+from vds_jira_orchestrator.adapter import JiraAdapter
+
+
+@patch("vds_jira_orchestrator.adapter.Jira")
+def test_get_createmeta_falls_back_to_rest_endpoint(mock_jira: MagicMock) -> None:
+    client = MagicMock()
+    client.issue_createmeta.side_effect = Exception("boom")
+    client.resource_url.return_value = "https://jira.example.com/rest/api/2/issue"
+    client.get.return_value = {"projects": []}
+    mock_jira.return_value = client
+
+    adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+    result = adapter.get_createmeta("TEST", issuetype="Task", expand="projects.issuetypes.fields")
+
+    client.get.assert_called_once_with(
+        "https://jira.example.com/rest/api/2/issue/createmeta",
+        params={
+            "projectKeys": "TEST",
+            "issuetypeNames": "Task",
+            "expand": "projects.issuetypes.fields",
+        },
+    )
+    assert result == {"projects": []}
+
+
+@patch("vds_jira_orchestrator.adapter.Jira")
+def test_get_createmeta_falls_back_when_v2_unavailable(mock_jira: MagicMock) -> None:
+    client = MagicMock()
+    response = MagicMock()
+    response.status_code = 404
+    client.issue_createmeta_issuetypes.side_effect = requests.exceptions.HTTPError(response=response)
+    client.issue_createmeta_fieldtypes.return_value = {}
+    client.issue_createmeta.return_value = {"projects": []}
+    mock_jira.return_value = client
+
+    adapter = JiraAdapter(url="https://jira.example.com", username="user", password="pass")
+    result = adapter.get_createmeta("TEST", issuetype="Task", expand="projects.issuetypes.fields")
+
+    client.issue_createmeta.assert_called_once()
+    assert result == {"projects": []}