@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/models/evidence.py

@@ -1,351 +0,0 @@
-"""Evidence models for content-based analysis (Phase 4).
-
-This module defines the core data models for evidence collection and management
-in the VDS Audit Orchestrator. Evidence is collected from various sources
-(git files, Confluence, Jira, SonarQube) and evaluated against requirements.
-
-Reference: design.md Section 3.3
-"""
-
-from __future__ import annotations
-
-import hashlib
-from datetime import datetime
-from enum import StrEnum
-from typing import TYPE_CHECKING, Any
-
-from pydantic import BaseModel, Field, computed_field, field_validator
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.profiles.models import ProjectProfile
-
-
-class EvidenceStatus(StrEnum):
-    """Status of evidence collection and quality.
-
-    Reference: design.md Section 3.3
-    """
-
-    FOUND = "Found"
-    PARTIAL = "Partial"
-    MISSING = "Missing"
-    OUTDATED = "Outdated"
-    FAULTY = "Faulty"
-    NOT_APPLICABLE = "Not Applicable"
-
-
-def compute_content_hash(content: str) -> str:
-    """Compute SHA-256 hash of content for caching and deduplication.
-
-    Args:
-        content: The content string to hash.
-
-    Returns:
-        Hexadecimal SHA-256 hash of the content.
-
-    Example:
-        >>> compute_content_hash("Hello, World!")
-        'dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f'
-    """
-    return hashlib.sha256(content.encode("utf-8")).hexdigest()
-
-
-class Evidence(BaseModel):
-    """Collected evidence for audit evaluation.
-
-    Represents a piece of evidence collected from a source system
-    (git repository, Confluence, Jira, SonarQube) for use in audit checks.
-
-    Attributes:
-        source: Type of evidence source (git_file, confluence_page, jira_issue, sonarqube_metric)
-        source_id: Unique identifier within the source system
-        source_url: URL to access the evidence in the source system
-        title: Human-readable title of the evidence
-        content: Raw content of the evidence
-        content_hash: SHA-256 hash for caching and deduplication
-        status: Collection and quality status
-        collected_at: Timestamp when evidence was collected
-        last_modified: Last modification timestamp from source
-        author: Author or last modifier
-        completeness_score: Quality score (0.0-1.0) indicating content completeness
-        metadata: Additional source-specific metadata
-
-    Example:
-        >>> evidence = Evidence(
-        ...     source="git_file",
-        ...     source_id="README.md",
-        ...     title="Project README",
-        ...     content="# My Project\\n...",
-        ...     content_hash=compute_content_hash("# My Project\\n..."),
-        ...     status=EvidenceStatus.FOUND,
-        ... )
-    """
-
-    # Source identification
-    source: str = Field(
-        ...,
-        description="Evidence source type: git_file, confluence_page, jira_issue, sonarqube_metric",
-    )
-    source_id: str = Field(..., description="Unique identifier within the source system")
-    source_url: str | None = Field(default=None, description="URL to access evidence in source system")
-
-    # Content
-    title: str = Field(..., description="Human-readable title")
-    content: str = Field(..., description="Raw content of the evidence")
-    content_hash: str = Field(..., description="SHA-256 hash for caching")
-
-    # Status
-    status: EvidenceStatus = Field(..., description="Collection and quality status")
-    collected_at: datetime = Field(default_factory=datetime.now, description="When evidence was collected")
-
-    # Quality indicators
-    last_modified: datetime | None = Field(default=None, description="Last modification in source system")
-    author: str | None = Field(default=None, description="Author or last modifier")
-    completeness_score: float = Field(
-        default=0.0,
-        ge=0.0,
-        le=1.0,
-        description="Content completeness score (0.0-1.0)",
-    )
-
-    # Metadata
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Source-specific metadata")
-
-    @field_validator("source")
-    @classmethod
-    def _validate_source(cls, v: str) -> str:
-        """Validate source is a known type."""
-        valid_sources = {"git_file", "confluence_page", "jira_issue", "sonarqube_metric"}
-        if v not in valid_sources:
-            # Allow unknown sources but normalize
-            pass
-        return v.lower().strip()
-
-    @field_validator("completeness_score")
-    @classmethod
-    def _validate_completeness_score(cls, v: float) -> float:
-        """Ensure completeness score is within valid range."""
-        return max(0.0, min(1.0, v))
-
-
-class EvidenceRequirement(BaseModel):
-    """Defines evidence needed for an audit check.
-
-    Specifies what evidence should be collected and the criteria for
-    evaluating its quality and completeness.
-
-    Attributes:
-        source: Required source type
-        path_pattern: Glob pattern for git file paths
-        page_title_pattern: Pattern for matching Confluence page titles
-        issue_jql: JQL query for Jira issues
-        required_sections: Sections that must be present in content
-        required_keywords: Keywords that must appear in content
-        min_content_length: Minimum acceptable content length
-        max_age_days: Maximum age of evidence in days (None = no limit)
-        weight: Importance weight for scoring
-        critical: Whether this requirement is critical (blocks passing)
-
-    Example:
-        >>> req = EvidenceRequirement(
-        ...     source="git_file",
-        ...     path_pattern="**/README.md",
-        ...     required_sections=["Installation", "Usage"],
-        ...     required_keywords=["docker", "kubernetes"],
-        ...     min_content_length=500,
-        ...     critical=True,
-        ... )
-    """
-
-    source: str = Field(
-        ...,
-        description="Required source type: git_file, confluence_page, jira_issue, sonarqube_metric",
-    )
-
-    # Source-specific patterns
-    path_pattern: str | None = Field(default=None, description="Glob pattern for git file paths")
-    page_title_pattern: str | None = Field(default=None, description="Pattern for Confluence page titles")
-    issue_jql: str | None = Field(default=None, description="JQL query for Jira issues")
-
-    # Content requirements
-    required_sections: list[str] = Field(default_factory=list, description="Sections that must be present")
-    required_keywords: list[str] = Field(default_factory=list, description="Keywords that must appear")
-    min_content_length: int = Field(default=0, ge=0, description="Minimum content length in characters")
-    max_age_days: int | None = Field(default=None, ge=1, description="Maximum age of evidence in days")
-
-    # Scoring
-    weight: float = Field(default=1.0, ge=0.0, description="Importance weight for scoring")
-    critical: bool = Field(default=False, description="Whether requirement is critical")
-
-    @field_validator("source")
-    @classmethod
-    def _validate_source(cls, v: str) -> str:
-        """Validate and normalize source type."""
-        return v.lower().strip()
-
-    @field_validator("required_sections", "required_keywords", mode="before")
-    @classmethod
-    def _normalize_lists(cls, v: Any) -> list[str]:
-        """Normalize list fields."""
-        if v is None:
-            return []
-        if isinstance(v, str):
-            return [v]
-        return list(v)
-
-
-class EvidenceBundle(BaseModel):
-    """Complete evidence bundle for a repository audit.
-
-    Aggregates all collected evidence from various sources for a single
-    repository audit, with computed statistics.
-
-    Attributes:
-        repository: Repository identifier (slug or name)
-        profile: Project profile (forward reference)
-        collected_at: Bundle collection timestamp
-        git_evidence: Evidence from git repository files
-        confluence_evidence: Evidence from Confluence pages
-        jira_evidence: Evidence from Jira issues
-        sonarqube_evidence: Evidence from SonarQube metrics
-        total_evidence: Total count of evidence items (computed)
-        found_count: Count of FOUND evidence (computed)
-        missing_count: Count of MISSING evidence (computed)
-        partial_count: Count of PARTIAL evidence (computed)
-
-    Example:
-        >>> bundle = EvidenceBundle(
-        ...     repository="my-service",
-        ...     git_evidence=[readme_evidence, changelog_evidence],
-        ...     confluence_evidence=[arch_doc_evidence],
-        ... )
-        >>> bundle.total_evidence
-        3
-        >>> bundle.found_count
-        2
-    """
-
-    repository: str = Field(..., description="Repository identifier")
-
-    # Profile as forward reference - use dict for serialization compatibility
-    # When ProjectProfile is available, it can be passed and will be converted
-    profile: dict[str, Any] = Field(default_factory=dict, description="Project profile data")
-
-    collected_at: datetime = Field(default_factory=datetime.now, description="Bundle collection timestamp")
-
-    # Evidence by source
-    git_evidence: list[Evidence] = Field(default_factory=list, description="Evidence from git files")
-    confluence_evidence: list[Evidence] = Field(default_factory=list, description="Evidence from Confluence")
-    jira_evidence: list[Evidence] = Field(default_factory=list, description="Evidence from Jira")
-    sonarqube_evidence: list[Evidence] = Field(default_factory=list, description="Evidence from SonarQube")
-    graphify_evidence: list[Evidence] = Field(
-        default_factory=list, description="Evidence from graphify knowledge graph"
-    )
-
-    # Phase 4: Multi-probe scoring support
-    primary_status: EvidenceStatus = Field(
-        default=EvidenceStatus.MISSING,
-        description="Primary evidence status from multi-probe evaluation",
-    )
-    combined_score: float | None = Field(
-        default=None,
-        ge=0.0,
-        le=10.0,
-        description="Combined score from multi-probe evaluation (0-10)",
-    )
-
-    # Metadata
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Bundle-level metadata")
-
-    @computed_field
-    @property
-    def total_evidence(self) -> int:
-        """Total count of all evidence items."""
-        return (
-            len(self.git_evidence)
-            + len(self.confluence_evidence)
-            + len(self.jira_evidence)
-            + len(self.sonarqube_evidence)
-            + len(self.graphify_evidence)
-        )
-
-    @computed_field
-    @property
-    def found_count(self) -> int:
-        """Count of evidence with FOUND status."""
-        return self._count_by_status(EvidenceStatus.FOUND)
-
-    @computed_field
-    @property
-    def missing_count(self) -> int:
-        """Count of evidence with MISSING status."""
-        return self._count_by_status(EvidenceStatus.MISSING)
-
-    @computed_field
-    @property
-    def partial_count(self) -> int:
-        """Count of evidence with PARTIAL status."""
-        return self._count_by_status(EvidenceStatus.PARTIAL)
-
-    def _count_by_status(self, status: EvidenceStatus) -> int:
-        """Count evidence items by status across all sources."""
-        count = 0
-        for evidence_list in [
-            self.git_evidence,
-            self.confluence_evidence,
-            self.jira_evidence,
-            self.sonarqube_evidence,
-            self.graphify_evidence,
-        ]:
-            count += sum(1 for e in evidence_list if e.status == status)
-        return count
-
-    @property
-    def all_evidence(self) -> list[Evidence]:
-        """Get all evidence items from all sources."""
-        return (
-            self.git_evidence
-            + self.confluence_evidence
-            + self.jira_evidence
-            + self.sonarqube_evidence
-            + self.graphify_evidence
-        )
-
-    @property
-    def outdated_count(self) -> int:
-        """Count of evidence with OUTDATED status."""
-        return self._count_by_status(EvidenceStatus.OUTDATED)
-
-    @property
-    def faulty_count(self) -> int:
-        """Count of evidence with FAULTY status."""
-        return self._count_by_status(EvidenceStatus.FAULTY)
-
-    def get_evidence_by_source(self, source: str) -> list[Evidence]:
-        """Get evidence items filtered by source type.
-
-        Args:
-            source: Source type to filter by.
-
-        Returns:
-            List of evidence items from the specified source.
-        """
-        source_map = {
-            "git_file": self.git_evidence,
-            "confluence_page": self.confluence_evidence,
-            "jira_issue": self.jira_evidence,
-            "sonarqube_metric": self.sonarqube_evidence,
-            "graphify_graph": self.graphify_evidence,
-            "graphify_architecture": self.graphify_evidence,
-            "graphify_documentation": self.graphify_evidence,
-            "graphify_dependency": self.graphify_evidence,
-        }
-        return source_map.get(source.lower(), [])
-
-    def set_profile(self, profile: ProjectProfile) -> None:
-        """Set the project profile from a ProjectProfile instance.
-
-        Args:
-            profile: ProjectProfile instance to set.
-        """
-        self.profile = profile.model_dump()