@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/engine/cl003_shared_lib_guard.py

@@ -1,194 +0,0 @@
-"""CL-003 shared-library guard — public thin API (TSK-133.8 / TSK-133.13 / TSK-133.14).
-
-Exposes two public functions used by tests and can be imported independently:
-
-- ``is_vds_lib_anchor(ref)`` — True when a ref string is a valid CL-003 evidence anchor.
-- ``apply_cl003_post_eval_guard(...)`` — apply the post-eval outcome adjustments for CL-003 rows.
-
-Both delegate to the canonical implementations in ``confluence_checklist_contract`` and
-``row_evaluator`` respectively, avoiding duplication.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-from vds_audit_orchestrator.models.checklist import RowStatus
-
-# ---------------------------------------------------------------------------
-# VDS lib token constants (shared with row_evaluator constants)
-# ---------------------------------------------------------------------------
-
-_VDS_LIB_TOKENS: tuple[str, ...] = (
-    "vn.com.viettel.vds",
-    "vn.com.viettel",
-    "vds-kafka",
-    "vds-message-queue-adapter",
-    "vds-cache-adapter",
-    "internal-cache-lib",
-    "vds-database-adapter",
-    "vds-jpa",
-    "vds-keycloak-adapter",
-    "vds-common-lib",
-    "vds.lib.",
-    "vds.service.",
-    "vds.internal",
-)
-
-_BUILD_FILE_NAMES: tuple[str, ...] = (
-    "pom.xml",
-    "build.gradle",
-    "build.gradle.kts",
-)
-
-_CONFIG_EXTENSIONS: tuple[str, ...] = (
-    ".properties",
-    ".yml",
-    ".yaml",
-)
-
-_JAVA_EXTENSIONS: tuple[str, ...] = (
-    ".java",
-    ".kt",
-    ".kts",
-)
-
-_REJECT_TOKENS: tuple[str, ...] = (
-    "spring.io",
-    "docs.spring.io",
-    "stackoverflow",
-    "baeldung",
-    "/test/",
-    "/tests/",
-    "test/resources/",
-    "src/test/",
-)
-
-_PARTIAL_SCORE_CAP = 80.0
-
-
-def is_vds_lib_anchor(ref: str) -> bool:
-    """Return True when *ref* is a valid CL-003 shared-library evidence anchor.
-
-    Accepts refs that contain:
-    - Build file names (pom.xml, build.gradle, build.gradle.kts)
-    - Java/Kotlin source files with VDS package references
-    - Config files referencing VDS infrastructure namespaces
-    - Any ref containing a VDS group-ID token (vn.com.viettel.vds, vds-kafka, etc.)
-
-    Rejects:
-    - Generic documentation URLs (spring.io, baeldung, stackoverflow)
-    - Test fixture files
-    - Unrelated Confluence page references
-    """
-    if not ref:
-        return False
-    lowered = ref.strip().lower()
-
-    # Reject: known noise sources first
-    if any(token in lowered for token in _REJECT_TOKENS):
-        return False
-
-    # Accept: any ref that contains a VDS lib token — handles content-inline refs
-    # like "pom.xml:vn.com.viettel.vds:vds-common-lib:1.0.0"
-    if any(token in lowered for token in _VDS_LIB_TOKENS):
-        return True
-
-    # Accept: build files always relevant (they carry dependency declarations)
-    if any(
-        lowered == name or lowered.endswith(f"/{name}") or lowered.startswith(f"{name}:") for name in _BUILD_FILE_NAMES
-    ):
-        return True
-
-    # Accept: config files referencing kafka/datasource/cache infrastructure
-    if any(lowered.endswith(ext) or f"{ext}:" in lowered for ext in _CONFIG_EXTENSIONS) and any(
-        ns in lowered for ns in ("spring.kafka.", "app.cache.", "app.datasource.", "spring.redis.", "spring.data.")
-    ):
-        return True
-
-    # Accept: Java/Kotlin source files under infrastructure layer
-    return bool(any(lowered.endswith(ext) for ext in _JAVA_EXTENSIONS) and ("/infrastructure/" in lowered or "vn.com.viettel" in lowered))
-
-
-def apply_cl003_post_eval_guard(
-    *,
-    check_id: str,
-    status: RowStatus | str,
-    score: float,
-    anchors: list[str],
-    concerns_evaluated: int = 3,
-) -> dict[str, Any]:
-    """Apply CL-003 post-evaluation outcome adjustments.
-
-    Args:
-        check_id: The checklist row check ID.
-        status: The initial evaluation status (RowStatus or string value).
-        score: The initial evaluation score (0-100).
-        anchors: Evidence anchor ref strings for the result.
-        concerns_evaluated: Number of infrastructure concerns evaluated.
-
-    Returns:
-        A dict with keys:
-        - ``status``: Adjusted RowStatus
-        - ``score``: Adjusted score (float)
-        - ``guard_applied``: bool — True when the guard modified the outcome
-        - ``guard_reason``: str — reason code when guard_applied is True
-        - ``reason``: str — human-readable reason (may be empty)
-    """
-    # Normalise status to RowStatus
-    if isinstance(status, str):
-        try:
-            status_enum = RowStatus(status)
-        except ValueError:
-            status_enum = RowStatus.EVIDENCE_GAP
-    else:
-        status_enum = status
-
-    # Only applies to CL-003
-    if str(check_id or "").strip().upper() != "CL-003":
-        return {
-            "status": status_enum,
-            "score": score,
-            "guard_applied": False,
-            "guard_reason": "",
-            "reason": "",
-        }
-
-    has_vds_ref = any(is_vds_lib_anchor(ref) for ref in anchors)
-
-    result_status = status_enum
-    result_score = score
-    guard_applied = False
-    guard_reason = ""
-    reason = ""
-
-    if status_enum == RowStatus.PASS:
-        if concerns_evaluated < 2:
-            result_status = RowStatus.PARTIAL
-            result_score = min(result_score, _PARTIAL_SCORE_CAP)
-            guard_applied = True
-            guard_reason = "fewer_than_2_concerns_evaluated"
-            reason = "Cần đánh giá ít nhất 2 infrastructure concern độc lập để xác nhận PASS cho CL-003."
-        elif not has_vds_ref:
-            result_status = RowStatus.PARTIAL
-            result_score = min(result_score, _PARTIAL_SCORE_CAP)
-            guard_applied = True
-            guard_reason = "no_vds_lib_ref_in_anchors"
-            reason = (
-                "Evidence anchors phải chứa tham chiếu thực tế đến VDS shared library "
-                "(vn.com.viettel.vds, vds-kafka, vds-jpa, v.v.) trong build files hoặc source code."
-            )
-
-    if status_enum == RowStatus.PARTIAL and result_score > _PARTIAL_SCORE_CAP:
-        result_score = _PARTIAL_SCORE_CAP
-        guard_applied = True
-        guard_reason = "partial_score_capped"
-        reason = f"PARTIAL score capped at {_PARTIAL_SCORE_CAP}."
-
-    return {
-        "status": result_status,
-        "score": result_score,
-        "guard_applied": guard_applied,
-        "guard_reason": guard_reason,
-        "reason": reason,
-    }

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/engine/companion_context_service.py

@@ -1,445 +0,0 @@
-"""Companion Context Service for bounded skill-assisted context generation.
-
-Phase 125: TSK-125.3 - Repomix-skill bounded integration
-
-This service generates bounded companion context artifacts using repomix-skill.
-Key characteristics:
-- Requires explicit repo scope (no open-ended searches)
-- Uses narrow include/ignore filters to avoid token bloat
-- Generates artifacts with explicit output paths and metadata
-- Artifacts are companion context only, NOT authoritative evidence
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import subprocess
-import time
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any
-
-import structlog
-from vds_agent_core.skills.executor import SkillExecutor
-
-logger = structlog.get_logger(__name__)
-
-
-# Default filters to exclude low-signal files
-DEFAULT_IGNORE_PATTERNS = [
-    # Dependencies
-    "node_modules/**",
-    "vendor/**",
-    ".venv/**",
-    "venv/**",
-    "__pycache__/**",
-    # Build outputs
-    "dist/**",
-    "build/**",
-    "target/**",
-    "*.class",
-    "*.jar",
-    "*.war",
-    # Lock files
-    "package-lock.json",
-    "yarn.lock",
-    "poetry.lock",
-    "uv.lock",
-    # Generated files
-    "*.generated.*",
-    "*.min.js",
-    "*.min.css",
-    # Test fixtures and mocks
-    "test/fixtures/**",
-    "tests/fixtures/**",
-    "__mocks__/**",
-    # IDE files
-    ".idea/**",
-    ".vscode/**",
-    "*.iml",
-    # Git
-    ".git/**",
-    ".gitignore",
-    # Documentation that doesn't need packing
-    "docs/changelog/**",
-    "docs/releases/**",
-    "CHANGELOG.md",
-    "CHANGELOG.*",
-]
-
-
-@dataclass
-class CompanionContextRequest:
-    """Request for companion context generation.
-
-    Attributes:
-        repo_path: Explicit repository path (required, no open-ended scope)
-        include_patterns: Narrow include filters (e.g., ["src/**/*.py", "config/*.yaml"])
-        ignore_patterns: Additional ignore patterns beyond defaults
-        output_path: Explicit output path for generated artifact
-        context_purpose: Description of why this context is needed (for metadata)
-        check_id: Optional check ID this context supports
-        row_id: Optional row ID this context supports
-        max_tokens: Maximum tokens budget (default: 50K)
-        max_file_size_kb: Maximum individual file size in KB (default: 100)
-    """
-
-    repo_path: str
-    include_patterns: list[str]
-    output_path: str
-    context_purpose: str
-    check_id: str | None = None
-    row_id: str | None = None
-    ignore_patterns: list[str] = field(default_factory=list)
-    max_tokens: int = 50000
-    max_file_size_kb: int = 100
-
-    def __post_init__(self) -> None:
-        """Validate request has required explicit scope."""
-        if not self.repo_path:
-            raise ValueError("repo_path is required for companion context (no open-ended scope)")
-        if not self.include_patterns:
-            raise ValueError("include_patterns must be specified for bounded context")
-        if not self.output_path:
-            raise ValueError("output_path is required for companion context generation")
-
-
-@dataclass
-class CompanionContextArtifact:
-    """Generated companion context artifact with metadata.
-
-    Attributes:
-        artifact_path: Path to the generated artifact file
-        source_repo: Repository this context was generated from
-        include_patterns: Filters used for generation
-        ignore_patterns: Ignore patterns applied
-        token_count: Approximate token count of generated context
-        file_count: Number of files included in the artifact
-        generation_time_ms: Time taken to generate in milliseconds
-        context_purpose: Purpose description from request
-        check_id: Check ID this context supports (if any)
-        row_id: Row ID this context supports (if any)
-        skill_name: Name of the skill that generated this context
-        is_companion_only: Always True - marks this as non-authoritative
-    """
-
-    artifact_path: str
-    source_repo: str
-    include_patterns: list[str]
-    ignore_patterns: list[str]
-    token_count: int
-    file_count: int
-    generation_time_ms: int
-    context_purpose: str
-    check_id: str | None
-    row_id: str | None
-    skill_name: str = "repomix-skill"
-    is_companion_only: bool = True  # Always True - companion context is NOT authoritative evidence
-
-    def to_metadata_dict(self) -> dict[str, Any]:
-        """Convert artifact metadata to dictionary for serialization."""
-        return {
-            "artifact_path": self.artifact_path,
-            "source_repo": self.source_repo,
-            "include_patterns": self.include_patterns,
-            "ignore_patterns": self.ignore_patterns,
-            "token_count": self.token_count,
-            "file_count": self.file_count,
-            "generation_time_ms": self.generation_time_ms,
-            "context_purpose": self.context_purpose,
-            "check_id": self.check_id,
-            "row_id": self.row_id,
-            "skill_name": self.skill_name,
-            "is_companion_only": self.is_companion_only,
-        }
-
-
-class CompanionContextService:
-    """Service for generating bounded companion context using repomix-skill.
-
-    Phase 125: TSK-125.3
-
-    This service wraps repomix-skill to generate tightly scoped companion context
-    for audit workflows. The generated artifacts are explicitly marked as companion
-    context only and should NOT be used as authoritative evidence.
-
-    Usage:
-        service = CompanionContextService()
-        request = CompanionContextRequest(
-            repo_path="/path/to/repo",
-            include_patterns=["src/api/**/*.py"],
-            output_path="/output/companion-api-context.txt",
-            context_purpose="Support API compliance check CL-003",
-            check_id="CL-003",
-        )
-        artifact = service.generate_context(request)
-        # artifact.is_companion_only == True (always)
-    """
-
-    def __init__(self) -> None:
-        """Initialize companion context service."""
-        self._skill_name = "repomix-skill"
-
-    def generate_context(
-        self,
-        request: CompanionContextRequest,
-    ) -> CompanionContextArtifact:
-        """Generate bounded companion context artifact.
-
-        Args:
-            request: Context generation request with explicit scope and filters
-
-        Returns:
-            CompanionContextArtifact with metadata
-
-        Raises:
-            ValueError: If request validation fails
-            RuntimeError: If repomix-skill execution fails
-        """
-        start_time = time.monotonic()
-
-        # Validate request
-        if not request.repo_path:
-            raise ValueError("repo_path is required for companion context (no open-ended scope)")
-        if not request.include_patterns:
-            raise ValueError("include_patterns must be specified for bounded context")
-        if not request.output_path:
-            raise ValueError("output_path is required for companion context generation")
-
-        logger.info(
-            "companion_context_generation_start",
-            repo_path=request.repo_path,
-            include_patterns=request.include_patterns,
-            check_id=request.check_id,
-            row_id=request.row_id,
-        )
-
-        # Prepare output directory
-        output_dir = Path(request.output_path).parent
-        output_dir.mkdir(parents=True, exist_ok=True)
-
-        # Build repomix command
-        # repomix outputs a single packed file with all matched code
-        cmd = self._build_repomix_command(request)
-
-        # Record skill invocation for telemetry
-        SkillExecutor.record_tool_usage(
-            {
-                "tool": self._skill_name,
-                "action": "generate_companion_context",
-                "repo_path": request.repo_path,
-                "check_id": request.check_id,
-                "row_id": request.row_id,
-                "status": "started",
-            }
-        )
-
-        # Execute repomix-skill
-        try:
-            result = subprocess.run(
-                cmd,
-                capture_output=True,
-                text=True,
-                timeout=120,  # 2 minute timeout
-            )
-
-            generation_time_ms = int((time.monotonic() - start_time) * 1000)
-
-            if result.returncode != 0:
-                error_msg = result.stderr or result.stdout
-                logger.error(
-                    "companion_context_generation_failed",
-                    repo_path=request.repo_path,
-                    error=error_msg,
-                    returncode=result.returncode,
-                )
-                SkillExecutor.record_tool_usage(
-                    {
-                        "tool": self._skill_name,
-                        "action": "generate_companion_context",
-                        "repo_path": request.repo_path,
-                        "check_id": request.check_id,
-                        "row_id": request.row_id,
-                        "status": "failed",
-                        "error": error_msg,
-                    }
-                )
-                raise RuntimeError(f"repomix-skill execution failed: {error_msg}")
-
-            # Parse output metadata
-            token_count, file_count = self._parse_repomix_output(result.stdout)
-
-            logger.info(
-                "companion_context_generation_complete",
-                repo_path=request.repo_path,
-                artifact_path=request.output_path,
-                token_count=token_count,
-                file_count=file_count,
-                generation_time_ms=generation_time_ms,
-            )
-
-            SkillExecutor.record_tool_usage(
-                {
-                    "tool": self._skill_name,
-                    "action": "generate_companion_context",
-                    "repo_path": request.repo_path,
-                    "check_id": request.check_id,
-                    "row_id": request.row_id,
-                    "status": "success",
-                    "token_count": token_count,
-                    "file_count": file_count,
-                }
-            )
-
-            # Create artifact with metadata
-            artifact = CompanionContextArtifact(
-                artifact_path=request.output_path,
-                source_repo=request.repo_path,
-                include_patterns=request.include_patterns,
-                ignore_patterns=request.ignore_patterns,
-                token_count=token_count,
-                file_count=file_count,
-                generation_time_ms=generation_time_ms,
-                context_purpose=request.context_purpose,
-                check_id=request.check_id,
-                row_id=request.row_id,
-                skill_name=self._skill_name,
-                is_companion_only=True,  # ALWAYS True - companion context is NOT authoritative
-            )
-
-            # Write metadata sidecar
-            self._write_metadata_sidecar(artifact)
-
-            return artifact
-
-        except subprocess.TimeoutExpired as exc:
-            generation_time_ms = int((time.monotonic() - start_time) * 1000)
-            logger.exception(
-                "companion_context_generation_timeout",
-                repo_path=request.repo_path,
-                timeout_ms=120000,
-            )
-            SkillExecutor.record_tool_usage(
-                {
-                    "tool": self._skill_name,
-                    "action": "generate_companion_context",
-                    "repo_path": request.repo_path,
-                    "check_id": request.check_id,
-                    "row_id": request.row_id,
-                    "status": "timeout",
-                }
-            )
-            raise RuntimeError("repomix-skill execution timed out after 120 seconds") from exc
-
-    def _build_repomix_command(self, request: CompanionContextRequest) -> list[str]:
-        """Build repomix CLI command with narrow filters."""
-        cmd = [
-            "npx",
-            "repomix",
-            "--output",
-            request.output_path,
-            "--style",
-            "plain",
-            "--no-file-summary",
-            "--remove-comments",
-            "--remove-empty-lines",
-        ]
-
-        # Add include patterns (narrow scope)
-        for pattern in request.include_patterns:
-            cmd.extend(["--include", pattern])
-
-        # Add default ignore patterns + custom ignores
-        all_ignores = DEFAULT_IGNORE_PATTERNS + list(request.ignore_patterns)
-        for pattern in all_ignores:
-            cmd.extend(["--ignore", pattern])
-
-        # Add file size limit
-        cmd.extend(["--max-file-size", f"{request.max_file_size_kb}KB"])
-
-        # Add token budget
-        cmd.extend(["--max-tokens", str(request.max_tokens)])
-
-        # Add repo path (explicit scope)
-        cmd.append(request.repo_path)
-
-        return cmd
-
-    def _parse_repomix_output(self, stdout: str) -> tuple[int, int]:
-        """Parse repomix output for token and file counts."""
-        # repomix outputs summary statistics
-        # Example: "Total files: 42, Total tokens: 15,234"
-        token_count = 0
-        file_count = 0
-
-        for line in stdout.split("\n"):
-            if "Total tokens:" in line or "tokens:" in line.lower():
-                try:
-                    token_str = line.split(":")[-1].strip().replace(",", "")
-                    token_count = int(token_str)
-                except (ValueError, IndexError):
-                    pass
-            if "Total files:" in line or "files:" in line.lower():
-                try:
-                    file_str = line.split(":")[-1].strip().replace(",", "")
-                    file_count = int(file_str)
-                except (ValueError, IndexError):
-                    pass
-
-        return token_count, file_count
-
-    def _write_metadata_sidecar(self, artifact: CompanionContextArtifact) -> None:
-        """Write JSON metadata sidecar alongside artifact."""
-        metadata_path = f"{artifact.artifact_path}.metadata.json"
-        with open(metadata_path, "w") as f:
-            json.dump(artifact.to_metadata_dict(), f, indent=2)
-
-        logger.debug(
-            "companion_context_metadata_written",
-            metadata_path=metadata_path,
-            artifact_path=artifact.artifact_path,
-        )
-
-
-def create_companion_context_for_check(
-    repo_path: str,
-    check_id: str,
-    include_patterns: list[str],
-    output_dir: str,
-    row_id: str | None = None,
-    context_purpose: str | None = None,
-) -> CompanionContextArtifact:
-    """Convenience function to create companion context for a specific check.
-
-    This is a helper that wraps the full service for common audit workflows.
-
-    Args:
-        repo_path: Explicit repository path (required)
-        check_id: Check ID this context supports
-        include_patterns: Narrow include filters
-        output_dir: Directory for output artifacts
-        row_id: Optional row ID
-        context_purpose: Optional purpose description
-
-    Returns:
-        CompanionContextArtifact with metadata
-    """
-    # Generate deterministic output filename based on inputs
-    hash_input = f"{repo_path}:{check_id}:{':'.join(include_patterns)}"
-    hash_digest = hashlib.sha256(hash_input.encode()).hexdigest()[:8]
-    output_filename = f"companion-{check_id}-{hash_digest}.txt"
-    output_path = os.path.join(output_dir, output_filename)
-
-    request = CompanionContextRequest(
-        repo_path=repo_path,
-        include_patterns=include_patterns,
-        output_path=output_path,
-        context_purpose=context_purpose or f"Companion context for check {check_id}",
-        check_id=check_id,
-        row_id=row_id,
-    )
-
-    service = CompanionContextService()
-    return service.generate_context(request)