@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,309 +0,0 @@
-"""Material completeness report data models (Phase 126, FR-126.1, FR-126.2).
-
-This module defines the core data models for material completeness checking,
-including metrics, material status entries, and freshness tiers.
-
-Completeness checking quantifies how many required materials (pages, attachments,
-repos) are prepared in the cache versus missing, stale, or aging.
-
-Reference: .kiro/specs/audit-orchestrator/requirements.md FR-126.1, FR-126.2
-Phase 126 Package A (TSK-126.2)
-"""
-
-from __future__ import annotations
-
-import enum
-from datetime import datetime
-from typing import Any
-
-from pydantic import BaseModel, Field
-
-
-class FreshnessTier(enum.StrEnum):
-    """Freshness level for cached materials (AC-126.2.5).
-
-    Freshness tiers are computed using TTL baseline with optional remote signals:
-    - fresh: Cached within last 24 hours
-    - aging: Cached 24-48 hours ago
-    - stale: Cached >48 hours OR remote signal mismatch
-    - unknown: Not in cache and probe failed
-    """
-
-    fresh = "fresh"
-    aging = "aging"
-    stale = "stale"
-    unknown = "unknown"
-
-
-class MaterialType(enum.StrEnum):
-    """Types of materials that can be checked for completeness."""
-
-    page = "page"
-    attachment = "attachment"
-    repo = "repo"
-
-
-class MaterialRequirement(BaseModel):
-    """A requirement for a material that should be prepared.
-
-    Attributes:
-        material_type: Type of material (page, attachment, repo)
-        identifier: Unique identifier (page_id, attachment_id, repo_key)
-        project_key: Project namespace for the material
-        source: Where this requirement was discovered (registry, checklist, explicit)
-        priority: Importance level (optional, for sorting/filtering)
-        title: Human-readable title (optional)
-        metadata: Additional context about the requirement
-    """
-
-    material_type: MaterialType = Field(description="Type of material required")
-    identifier: str = Field(description="Unique identifier (page_id, attachment_id, repo_key)")
-    project_key: str = Field(description="Project namespace")
-    source: str = Field(description="Discovery source: registry, checklist, explicit")
-    priority: int = Field(default=0, description="Higher priority = more important")
-    title: str | None = Field(default=None, description="Human-readable title")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional context")
-
-
-class CompletenessMetrics(BaseModel):
-    """Aggregate completeness metrics for a project (AC-126.1.3).
-
-    Attributes:
-        total_required: Total number of required materials discovered
-        total_prepared: Number of materials found in cache (any freshness)
-        total_missing: Number of materials not found in cache
-        total_stale: Number of materials marked as stale
-        total_aging: Number of materials marked as aging
-        completeness_pct: Percentage of required materials that are prepared
-        freshness_pct: Percentage of prepared materials that are fresh
-        avg_freshness_hours: Average age of cached materials in hours
-        cache_hit_rate: Percentage of material lookups that hit cache
-        deep_checked: Whether remote signal validation was performed
-        checked_at: Timestamp when metrics were computed
-    """
-
-    total_required: int = Field(ge=0, description="Total required materials")
-    total_prepared: int = Field(ge=0, description="Materials found in cache")
-    total_missing: int = Field(ge=0, description="Materials not in cache")
-    total_stale: int = Field(ge=0, description="Materials marked as stale")
-    total_aging: int = Field(ge=0, description="Materials marked as aging")
-    completeness_pct: float = Field(ge=0, le=100, description="Prepared / required * 100")
-    freshness_pct: float = Field(ge=0, le=100, description="Fresh / prepared * 100")
-    avg_freshness_hours: float = Field(ge=0, description="Average cache age in hours")
-    cache_hit_rate: float = Field(ge=0, le=100, description="Cache hit percentage")
-    deep_checked: bool = Field(default=False, description="Remote validation performed")
-    checked_at: datetime = Field(default_factory=datetime.now, description="Metrics timestamp")
-
-    def get_freshness_summary(self) -> dict[str, int]:
-        """Return freshness distribution as a summary dict.
-
-        Useful for quick status reporting without full material lists.
-        """
-        total = self.total_prepared + self.total_missing
-        fresh_count = self.total_prepared - self.total_stale - self.total_aging
-        return {
-            "fresh": max(0, fresh_count),
-            "aging": self.total_aging,
-            "stale": self.total_stale,
-            "unknown": self.total_missing,
-            "total": total,
-        }
-
-
-class PreparedMaterial(BaseModel):
-    """A material that was found in the cache.
-
-    Attributes:
-        material_type: Type of material (page, attachment, repo)
-        identifier: Unique identifier
-        project_key: Project namespace
-        title: Human-readable title if available
-        cached_at: When the material was cached
-        freshness: Freshness tier (fresh, aging, stale)
-        last_accessed: When the material was last accessed (if tracked)
-        content_hash: Content checksum for deduplication
-        age_hours: How long since cached (in hours)
-        cache_path: Filesystem path to cached content (if available)
-        metadata: Additional cache entry metadata
-    """
-
-    material_type: MaterialType = Field(description="Type of material")
-    identifier: str = Field(description="Unique identifier")
-    project_key: str = Field(description="Project namespace")
-    title: str | None = Field(default=None, description="Material title")
-    cached_at: datetime = Field(description="When cached")
-    freshness: FreshnessTier = Field(description="Freshness tier")
-    last_accessed: datetime | None = Field(default=None, description="Last access timestamp")
-    content_hash: str | None = Field(default=None, description="Content checksum")
-    age_hours: float = Field(ge=0, description="Age in hours")
-    cache_path: str | None = Field(default=None, description="Cache file path")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
-
-
-class MissingMaterial(BaseModel):
-    """A required material that was not found in the cache.
-
-    Attributes:
-        material_type: Type of material (page, attachment, repo)
-        identifier: Unique identifier
-        project_key: Project namespace
-        reason: Why the material is considered missing
-        last_cache_attempt: When we last tried to cache this (if known)
-        metadata: Additional context
-    """
-
-    material_type: MaterialType = Field(description="Type of material")
-    identifier: str = Field(description="Unique identifier")
-    project_key: str = Field(description="Project namespace")
-    reason: str = Field(description="Missing reason: not_in_cache, not_found_in_remote, unsupported_type")
-    last_cache_attempt: datetime | None = Field(default=None, description="Last cache attempt")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional context")
-
-
-class StaleMaterial(BaseModel):
-    """A material that is in cache but marked as stale.
-
-    Attributes:
-        material_type: Type of material (page, attachment, repo)
-        identifier: Unique identifier
-        project_key: Project namespace
-        stale_reason: Why the material is considered stale
-        cached_at: When the material was cached
-        age_hours: How long since cached
-        remote_version: Version from remote signal (if available)
-        cached_version: Version in cache metadata
-        recommended_action: Suggested action to resolve staleness
-        metadata: Additional context
-    """
-
-    material_type: MaterialType = Field(description="Type of material")
-    identifier: str = Field(description="Unique identifier")
-    project_key: str = Field(description="Project namespace")
-    stale_reason: str = Field(description="Reason: ttl_expired, remote_changed, version_mismatch")
-    cached_at: datetime = Field(description="When cached")
-    age_hours: float = Field(ge=0, description="Age in hours")
-    remote_version: str | None = Field(default=None, description="Remote version")
-    cached_version: str | None = Field(default=None, description="Cached version")
-    recommended_action: str = Field(default="refresh", description="Suggested action: refresh, deep_check, ignore")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional context")
-
-
-class CompletenessAction(BaseModel):
-    """A recommended action to improve completeness.
-
-    Generated from completeness analysis to guide users on what to do next.
-
-    Attributes:
-        action_type: Category of action (download, refresh, deep_check, ignore)
-        priority: Urgency (critical, high, medium, low)
-        description: Human-readable description
-        affected_materials: List of material identifiers this action applies to
-        estimated_effort: Rough effort estimate (if applicable)
-        command_suggestion: Suggested CLI command (if applicable)
-    """
-
-    action_type: str = Field(description="Action category: download, refresh, deep_check, ignore")
-    priority: str = Field(description="Priority: critical, high, medium, low")
-    description: str = Field(description="Human-readable description")
-    affected_materials: list[str] = Field(default_factory=list, description="Material identifiers this applies to")
-    estimated_effort: str | None = Field(default=None, description="Effort estimate")
-    command_suggestion: str | None = Field(default=None, description="Suggested CLI command")
-
-
-class CompletenessReport(BaseModel):
-    """Full completeness report for a project (AC-126.1.4, AC-126.1.5).
-
-    This is the primary output of the MaterialCompletenessService, containing
-    metrics, detailed material lists, and recommended actions.
-
-    Attributes:
-        metrics: Aggregate completeness metrics
-        prepared: List of materials found in cache
-        missing: List of materials not found in cache
-        stale: List of materials marked as stale
-        actions: Recommended actions to improve completeness
-        project_key: Project namespace
-        checked_at: Timestamp when report was generated
-        deep_checked: Whether remote validation was performed
-        cache_dir: Path to the cache directory used
-        source_summary: Breakdown of requirement sources
-    """
-
-    metrics: CompletenessMetrics = Field(description="Aggregate metrics")
-    prepared: list[PreparedMaterial] = Field(default_factory=list, description="Materials in cache")
-    missing: list[MissingMaterial] = Field(default_factory=list, description="Materials not in cache")
-    stale: list[StaleMaterial] = Field(default_factory=list, description="Materials marked stale")
-    actions: list[CompletenessAction] = Field(default_factory=list, description="Recommended actions")
-    project_key: str = Field(description="Project namespace")
-    checked_at: datetime = Field(default_factory=datetime.now, description="Report timestamp")
-    deep_checked: bool = Field(default=False, description="Remote validation performed")
-    cache_dir: str | None = Field(default=None, description="Cache directory path")
-    source_summary: dict[str, int] = Field(
-        default_factory=dict,
-        description="Breakdown of requirement sources (registry, checklist, explicit)",
-    )
-
-    def get_readiness_status(self, threshold_pct: float = 80.0) -> str:
-        """Determine readiness status based on completeness threshold (AC-126.5.2).
-
-        Args:
-            threshold_pct: Minimum acceptable completeness percentage (default 80%)
-
-        Returns:
-            Status string: ready, needs_attention, critical
-        """
-        if self.metrics.completeness_pct >= threshold_pct:
-            return "ready"
-        if self.metrics.completeness_pct >= threshold_pct / 2:
-            return "needs_attention"
-        return "critical"
-
-    def get_summary_text(self) -> str:
-        """Generate human-readable summary text.
-
-        Useful for CLI output and quick status display.
-        """
-        lines = [
-            f"Completeness Report for {self.project_key}",
-            f"  Prepared: {self.metrics.total_prepared}/{self.metrics.total_required} "
-            f"({self.metrics.completeness_pct:.1f}%)",
-        ]
-
-        if self.metrics.total_missing > 0:
-            lines.append(f"  Missing: {self.metrics.total_missing}")
-        if self.metrics.total_stale > 0:
-            lines.append(f"  Stale: {self.metrics.total_stale}")
-        if self.metrics.total_aging > 0:
-            lines.append(f"  Aging: {self.metrics.total_aging}")
-
-        freshness_summary = self.metrics.get_freshness_summary()
-        lines.append(
-            f"  Freshness: {freshness_summary['fresh']} fresh, "
-            f"{freshness_summary['aging']} aging, {freshness_summary['stale']} stale"
-        )
-
-        if self.actions:
-            lines.append(f"  Recommended Actions: {len(self.actions)}")
-
-        return "\n".join(lines)
-
-    def to_dict_for_sync_metadata(self) -> dict[str, Any]:
-        """Convert to dict for storage in project_preparation.sync_metadata (AC-126.3.2).
-
-        This method produces a compact representation suitable for JSONB storage,
-        excluding verbose lists but keeping all metrics and summary data.
-
-        Returns:
-            Dict with keys: metrics, timestamp, deep_check, source_summary, readiness
-        """
-        return {
-            "metrics": self.metrics.model_dump(),
-            "timestamp": self.checked_at.isoformat(),
-            "deep_check": self.deep_checked,
-            "source_summary": self.source_summary,
-            "readiness_status": self.get_readiness_status(),
-            "prepared_count": len(self.prepared),
-            "missing_count": len(self.missing),
-            "stale_count": len(self.stale),
-            "actions_count": len(self.actions),
-        }

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

@@ -1,58 +0,0 @@
-"""Enrichment models for Phase 19 (TSK-183/184).
-
-Models for structured data extracted from Confluence pages (Tables, Mentions).
-"""
-
-from __future__ import annotations
-
-from enum import StrEnum
-
-from pydantic import BaseModel, Field
-
-
-class MentionType(StrEnum):
-    """Type of entity mentioned in text."""
-
-    JIRA = "JIRA"
-    BITBUCKET = "BITBUCKET"
-    CONFLUENCE = "CONFLUENCE"
-    EXTERNAL_URL = "EXTERNAL_URL"
-    UNKNOWN = "UNKNOWN"
-
-
-class ExtractedMention(BaseModel):
-    """A specific mention found in document text."""
-
-    type: MentionType
-    text: str
-    url: str | None = None
-    key: str | None = None  # e.g. Jira Key "TDOV-123"
-    context_surrounding: str | None = None
-    source_page_id: str
-
-
-class TableCell(BaseModel):
-    """A single cell in an extracted table."""
-
-    row: int
-    col: int
-    rowspan: int = 1
-    colspan: int = 1
-    text: str
-    is_header: bool = False
-    html: str | None = None  # Optional raw HTML if needed
-
-
-class ExtractedTable(BaseModel):
-    """A structured table extracted from a page."""
-
-    source_page_id: str
-    table_index: int
-    heading_context: str | None = None  # Heading immediately preceding the table
-    rows: int
-    cols: int
-    cells: list[TableCell] = Field(default_factory=list)
-
-    # Derived metadata
-    has_headers: bool = False
-    likely_type: str | None = None  # e.g. "matrix", "list", "layout"

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

@@ -1,97 +0,0 @@
-"""Pydantic enumerations for Audit Orchestrator.
-
-Defines standard enums for severity, priority, migration effort, check status,
-and CMMI maturity levels following the design specification exactly.
-
-Reference: design.md Section 6.1
-"""
-
-from __future__ import annotations
-
-from enum import StrEnum
-
-
-class Severity(StrEnum):
-    """Severity levels for audit findings.
-
-    Aligned with VDS security standards.
-    """
-
-    CRITICAL = "Critical"
-    HIGH = "High"
-    MEDIUM = "Medium"
-    LOW = "Low"
-    INFO = "Info"
-
-
-class Priority(StrEnum):
-    """Priority levels for remediation actions.
-
-    P1 = immediate action required, P4 = low priority/nice-to-have.
-    """
-
-    P1 = "P1"
-    P2 = "P2"
-    P3 = "P3"
-    P4 = "P4"
-
-
-class MigrationEffort(StrEnum):
-    """Estimated effort required to remediate a finding.
-
-    Used for planning and resource allocation.
-    """
-
-    LOW = "Low"
-    MEDIUM = "Medium"
-    HIGH = "High"
-    VERY_HIGH = "Very High"
-
-
-class CheckStatus(StrEnum):
-    """Status of an audit check execution.
-
-    Indicates the outcome of running a specific check against a repository.
-
-    Reference: design.md Section 6.1, FR-010.02
-    """
-
-    PASS = "PASS"
-    FAIL = "FAIL"
-    WARNING = "WARNING"
-    ERROR = "ERROR"
-    NA = "N/A"
-    SKIPPED = "SKIPPED"
-
-    # Backwards-compatible aliases used across scoring/reporting/checks
-    PASSED = "PASS"
-    FAILED = "FAIL"
-    PARTIAL = "WARNING"
-    NOT_APPLICABLE = "N/A"
-
-
-class MaturityLevel(StrEnum):
-    """CMMI-aligned maturity levels for scored evaluation (Phase 4).
-
-    Maps 0-10 scores to maturity levels for consistent assessment.
-    """
-
-    INITIAL = "INITIAL"  # 0-2: Ad hoc, reactive
-    REPEATABLE = "REPEATABLE"  # 2-4: Basic but inconsistent
-    DEFINED = "DEFINED"  # 4-6: Documented, standardized
-    MANAGED = "MANAGED"  # 6-8: Measured with KPIs
-    OPTIMIZING = "OPTIMIZING"  # 8-10: Continuous improvement
-
-    @classmethod
-    def from_score(cls, score: float) -> MaturityLevel:
-        """Map 0-10 score to maturity level."""
-        if score < 2:
-            return cls.INITIAL
-        elif score < 4:
-            return cls.REPEATABLE
-        elif score < 6:
-            return cls.DEFINED
-        elif score < 8:
-            return cls.MANAGED
-        else:
-            return cls.OPTIMIZING