npm - @ngocsangairvds/vsaf - Versions diffs - 3.2.13 → 3.2.15 - Mend

@ngocsangairvds/vsaf 3.2.13 → 3.2.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1441) hide show

package/tools/vds-scripts/audit_orchestrator/docs/MULTI_REPO_AUDIT_SPEC.md DELETED Viewed

@@ -1,951 +0,0 @@
-# Multi-Repository Content-Based Audit Specification
-**Version:** 1.0.0
-**Status:** DRAFT
-**Created:** 2026-01-31
----
-## 1. Overview
-This specification defines how the VDS Audit Orchestrator processes **three primary inputs** to generate content-based compliance scores:
-| Input | Description | Source |
-|-------|-------------|--------|
-| **Audit Template** | Excel/Google Sheets checklist with sections, checks, weights | VDS standard templates |
-| **Confluence Docs** | Project documentation pages | Confluence spaces |
-| **Project Git Link** | Parent project containing multiple repositories | Bitbucket/GitHub |
-### Multi-Repository Context
-VDS projects follow a **microservices architecture** with multiple repositories per project:
-```
-INSURANCE-project/
-├── ins-api-gateway/           # API Gateway service
-├── ins-policy-service/        # Policy management
-├── ins-claim-service/         # Claims processing
-├── ins-payment-service/       # Payment integration
-├── ins-notification-service/  # Notifications
-├── ins-admin-portal/          # Admin frontend
-├── ins-customer-portal/       # Customer frontend
-└── insurance-document/        # Documentation
-```
-Each repository is audited individually, then scores are aggregated at the project level.
----
-## 2. Input Processing Architecture
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         INPUT PROCESSING FLOW                               │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  INPUT 1: AUDIT TEMPLATE (Excel/Sheets)                                     │
-│  ┌──────────────────────────────────────────────────────────────────┐      │
-│  │ Sections:                                                         │      │
-│  │   ├── Documentation (weight: 15%)                                │      │
-│  │   ├── Code Quality (weight: 25%)                                 │      │
-│  │   ├── Security (weight: 30%)                                     │      │
-│  │   ├── Testing (weight: 20%)                                      │      │
-│  │   └── CI/CD (weight: 10%)                                        │      │
-│  │                                                                   │      │
-│  │ Checks per Section:                                               │      │
-│  │   ├── Check ID, Description, Expected Evidence                   │      │
-│  │   ├── Severity, Weight, Required flag                            │      │
-│  │   └── Check Type (plugin), Plugin Config                         │      │
-│  └──────────────────────────────────────────────────────────────────┘      │
-│           │                                                                 │
-│           ▼                                                                 │
-│  ┌──────────────────────────────────────────────────────────────────┐      │
-│  │ TEMPLATE PARSER                                                   │      │
-│  │   - Load sections and checks                                      │      │
-│  │   - Extract requirement keywords                                  │      │
-│  │   - Identify expected evidence types                              │      │
-│  │   - Determine applicable repos per check                          │      │
-│  └──────────────────────────────────────────────────────────────────┘      │
-│                                                                             │
-│  INPUT 2: CONFLUENCE DOCS                                                   │
-│  ┌──────────────────────────────────────────────────────────────────┐      │
-│  │ Space: INS (Insurance Project)                                    │      │
-│  │   ├── ins-architecture (Architecture Overview)                   │      │
-│  │   ├── ins-api-reference (API Documentation)                      │      │
-│  │   ├── ins-deployment-guide (Deployment Runbook)                  │      │
-│  │   ├── ins-security-guidelines (Security Policies)                │      │
-│  │   └── ins-onboarding (Developer Guide)                           │      │
-│  └──────────────────────────────────────────────────────────────────┘      │
-│           │                                                                 │
-│           ▼                                                                 │
-│  ┌──────────────────────────────────────────────────────────────────┐      │
-│  │ CONFLUENCE CRAWLER                                                │      │
-│  │   - Fetch page tree for project space                            │      │
-│  │   - Extract content, sections, code blocks                       │      │
-│  │   - Analyze documentation quality                                 │      │
-│  │   - Map pages to audit requirements                              │      │
-│  └──────────────────────────────────────────────────────────────────┘      │
-│                                                                             │
-│  INPUT 3: PROJECT GIT LINK (Multi-Repo)                                     │
-│  ┌──────────────────────────────────────────────────────────────────┐      │
-│  │ Project: INSURANCE-project                                        │      │
-│  │   ├── ins-api-gateway (repo)                                     │      │
-│  │   ├── ins-policy-service (repo)                                  │      │
-│  │   ├── ins-claim-service (repo)                                   │      │
-│  │   ├── ins-payment-service (repo)                                 │      │
-│  │   ├── ins-notification-service (repo)                            │      │
-│  │   ├── ins-admin-portal (repo)                                    │      │
-│  │   └── ins-customer-portal (repo)                                 │      │
-│  └──────────────────────────────────────────────────────────────────┘      │
-│           │                                                                 │
-│           ▼                                                                 │
-│  ┌──────────────────────────────────────────────────────────────────┐      │
-│  │ REPOSITORY DISCOVERY                                              │      │
-│  │   - List all repos in project                                    │      │
-│  │   - Classify by type (service, frontend, library, docs)          │      │
-│  │   - Clone/fetch for local analysis                               │      │
-│  │   - Determine applicable checks per repo type                    │      │
-│  └──────────────────────────────────────────────────────────────────┘      │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
----
-## 3. Data Models
-### 3.1 Audit Configuration
-```python
-@dataclass
-class AuditConfiguration:
-    """Complete audit configuration from inputs."""
-    # Template
-    template: AuditTemplate
-    template_source: str  # Path or Google Sheets URL
-    # Confluence
-    confluence_space: str
-    confluence_base_url: str
-    confluence_pages: list[ConfluencePageRef]
-    # Project repositories
-    project_key: str
-    project_name: str
-    repositories: list[RepositoryConfig]
-    # Audit settings
-    audit_mode: AuditMode  # FULL, INCREMENTAL, QUICK
-    parallel_repos: int  # Concurrent repo processing
-    skip_repos: list[str]  # Repos to exclude
-@dataclass
-class RepositoryConfig:
-    """Configuration for a single repository."""
-    name: str
-    clone_url: str
-    local_path: Path | None
-    repo_type: RepoType  # SERVICE, FRONTEND, LIBRARY, DOCS, CONFIG
-    language: str  # python, java, typescript, etc.
-    enabled: bool
-    applicable_sections: list[str]  # Which audit sections apply
-class RepoType(str, Enum):
-    """Repository classification."""
-    SERVICE = "service"           # Backend microservice
-    FRONTEND = "frontend"         # Web/mobile frontend
-    LIBRARY = "library"           # Shared library
-    DOCS = "docs"                 # Documentation repo
-    CONFIG = "config"             # Configuration/infra repo
-    GATEWAY = "gateway"           # API gateway
-    UNKNOWN = "unknown"
-```
-### 3.2 Multi-Repository Audit Result
-```python
-@dataclass
-class ProjectAuditResult:
-    """Aggregated audit result for entire project."""
-    project_key: str
-    project_name: str
-    audit_date: datetime
-    # Overall scores
-    overall_score: float           # 0-10 aggregated
-    overall_grade: str             # A-F
-    overall_maturity: MaturityLevel
-    # Repository results
-    repository_results: list[RepositoryAuditResult]
-    # Section aggregates (across all repos)
-    section_aggregates: list[SectionAggregate]
-    # Confluence documentation score
-    documentation_score: DocumentationScore
-    # Cross-cutting concerns
-    cross_repo_findings: list[CrossRepoFinding]
-    # Metadata
-    total_repos: int
-    repos_passed: int
-    repos_failed: int
-    audit_duration_seconds: float
-@dataclass
-class SectionAggregate:
-    """Aggregated section score across all repositories."""
-    section_id: str
-    section_name: str
-    weight: float
-    # Aggregated scores
-    average_score: float
-    min_score: float
-    max_score: float
-    median_score: float
-    # Repository breakdown
-    repo_scores: dict[str, float]  # repo_name -> score
-    # Maturity distribution
-    maturity_distribution: dict[MaturityLevel, int]
-    # Findings
-    common_issues: list[str]
-    best_practices: list[str]
-@dataclass
-class DocumentationScore:
-    """Score for Confluence documentation."""
-    overall_score: float
-    maturity_level: MaturityLevel
-    # Page scores
-    page_scores: dict[str, float]  # page_title -> score
-    # Coverage
-    required_pages_found: list[str]
-    required_pages_missing: list[str]
-    coverage_percentage: float
-    # Quality metrics
-    average_word_count: int
-    average_sections: int
-    has_api_docs: bool
-    has_architecture_docs: bool
-    has_deployment_docs: bool
-    has_security_docs: bool
-    # Recommendations
-    recommendations: list[str]
-```
----
-## 4. Repository Discovery & Classification
-### 4.1 Repository Discovery
-```python
-class RepositoryDiscovery:
-    """Discover and classify repositories in a project."""
-    def __init__(self, bitbucket_client: BitbucketClient):
-        self.client = bitbucket_client
-    async def discover_repositories(
-        self,
-        project_key: str,
-    ) -> list[RepositoryConfig]:
-        """Discover all repositories in a project."""
-        # Get all repos from Bitbucket
-        repos = await self.client.list_repositories(project_key)
-        repo_configs = []
-        for repo in repos:
-            # Classify repository type
-            repo_type = await self._classify_repo(repo)
-            # Detect primary language
-            language = await self._detect_language(repo)
-            # Determine applicable audit sections
-            applicable_sections = self._get_applicable_sections(repo_type, language)
-            repo_configs.append(RepositoryConfig(
-                name=repo.name,
-                clone_url=repo.clone_url,
-                local_path=None,
-                repo_type=repo_type,
-                language=language,
-                enabled=True,
-                applicable_sections=applicable_sections,
-            ))
-        return repo_configs
-    async def _classify_repo(self, repo: Repository) -> RepoType:
-        """Classify repository based on name and content."""
-        name = repo.name.lower()
-        # Name-based classification
-        if "gateway" in name or "api-gateway" in name:
-            return RepoType.GATEWAY
-        if "frontend" in name or "portal" in name or "ui" in name or "web" in name:
-            return RepoType.FRONTEND
-        if "lib" in name or "common" in name or "shared" in name or "sdk" in name:
-            return RepoType.LIBRARY
-        if "doc" in name or "document" in name:
-            return RepoType.DOCS
-        if "config" in name or "infra" in name or "deploy" in name:
-            return RepoType.CONFIG
-        if "service" in name or "-api" in name or "-svc" in name:
-            return RepoType.SERVICE
-        # Content-based classification (if name doesn't match)
-        files = await self.client.list_files(repo.slug, path="", limit=20)
-        file_names = [f.name.lower() for f in files]
-        if "package.json" in file_names and "src" in file_names:
-            if any("react" in f or "vue" in f or "angular" in f for f in file_names):
-                return RepoType.FRONTEND
-        if "pom.xml" in file_names or "build.gradle" in file_names:
-            return RepoType.SERVICE
-        if "pyproject.toml" in file_names or "setup.py" in file_names:
-            return RepoType.SERVICE
-        return RepoType.UNKNOWN
-    def _get_applicable_sections(
-        self,
-        repo_type: RepoType,
-        language: str,
-    ) -> list[str]:
-        """Determine which audit sections apply to this repo type."""
-        # Base sections that apply to all repos
-        base_sections = ["documentation", "security", "ci_cd"]
-        # Type-specific sections
-        type_sections = {
-            RepoType.SERVICE: ["code_quality", "testing", "api_design", "logging"],
-            RepoType.FRONTEND: ["code_quality", "testing", "accessibility", "performance"],
-            RepoType.LIBRARY: ["code_quality", "testing", "api_design", "versioning"],
-            RepoType.GATEWAY: ["security", "api_design", "performance", "rate_limiting"],
-            RepoType.DOCS: ["documentation"],
-            RepoType.CONFIG: ["security", "infrastructure"],
-        }
-        return base_sections + type_sections.get(repo_type, [])
-```
-### 4.2 Repository Type to Section Mapping
-```yaml
-# repo_section_mapping.yaml
-repository_types:
-  service:
-    description: "Backend microservice"
-    applicable_sections:
-      - documentation
-      - code_quality
-      - testing
-      - security
-      - ci_cd
-      - api_design
-      - logging
-      - error_handling
-    required_files:
-      - README.md
-      - pyproject.toml OR pom.xml OR build.gradle
-      - Dockerfile
-      - .gitlab-ci.yml OR Jenkinsfile
-  frontend:
-    description: "Web/mobile frontend"
-    applicable_sections:
-      - documentation
-      - code_quality
-      - testing
-      - security
-      - ci_cd
-      - accessibility
-      - performance
-    required_files:
-      - README.md
-      - package.json
-      - Dockerfile
-  library:
-    description: "Shared library/SDK"
-    applicable_sections:
-      - documentation
-      - code_quality
-      - testing
-      - versioning
-      - api_design
-    required_files:
-      - README.md
-      - CHANGELOG.md
-      - pyproject.toml OR package.json
-  gateway:
-    description: "API gateway"
-    applicable_sections:
-      - documentation
-      - security
-      - rate_limiting
-      - api_design
-      - ci_cd
-    required_files:
-      - README.md
-      - openapi.yaml OR swagger.yaml
-```
----
-## 5. Content Analysis Pipeline
-### 5.1 Per-Repository Analysis
-```python
-class RepositoryAnalyzer:
-    """Analyze a single repository for audit compliance."""
-    def __init__(
-        self,
-        code_collector: CodeEvidenceCollector,
-        semantic_matcher: SemanticMatcher,
-        compliance_scorer: ComplianceScorer,
-    ):
-        self.code_collector = code_collector
-        self.semantic_matcher = semantic_matcher
-        self.compliance_scorer = compliance_scorer
-    async def analyze(
-        self,
-        repo_config: RepositoryConfig,
-        template: AuditTemplate,
-        confluence_evidence: list[Evidence],
-    ) -> RepositoryAuditResult:
-        """Analyze repository against applicable template sections."""
-        repo_path = repo_config.local_path
-        applicable_sections = repo_config.applicable_sections
-        section_results = []
-        for section in template.sections:
-            # Skip non-applicable sections for this repo type
-            if section.id not in applicable_sections:
-                section_results.append(self._create_na_section(section))
-                continue
-            # Analyze each check in section
-            check_results = []
-            for check in section.checks:
-                result = await self._analyze_check(
-                    check=check,
-                    repo_path=repo_path,
-                    repo_config=repo_config,
-                    confluence_evidence=confluence_evidence,
-                )
-                check_results.append(result)
-            # Aggregate section score
-            section_score = self._aggregate_section(section, check_results)
-            section_results.append(section_score)
-        # Calculate overall repository score
-        return self._build_repo_result(repo_config, section_results)
-    async def _analyze_check(
-        self,
-        check: AuditCheck,
-        repo_path: Path,
-        repo_config: RepositoryConfig,
-        confluence_evidence: list[Evidence],
-    ) -> CheckResult:
-        """Analyze single check with content-based scoring."""
-        # 1. Extract requirement from check description
-        requirement = self.requirement_analyzer.analyze(check)
-        # 2. Collect code evidence
-        code_evidence = await self.code_collector.collect(repo_path, requirement)
-        # 3. Filter relevant Confluence evidence
-        relevant_confluence = self._filter_confluence_evidence(
-            confluence_evidence, requirement
-        )
-        # 4. Combine all evidence
-        all_evidence = code_evidence + relevant_confluence
-        # 5. Match requirement against evidence
-        match_result = await self.semantic_matcher.match(requirement, all_evidence)
-        # 6. Calculate compliance score
-        compliance = self.compliance_scorer.score(
-            requirement, all_evidence, match_result
-        )
-        return CheckResult(
-            check_id=check.id,
-            status=self._score_to_status(compliance.total_score),
-            score=compliance.total_score,
-            maturity_level=compliance.maturity_level,
-            evidence_sources={
-                "code": [e.source_id for e in code_evidence],
-                "confluence": [e.source_id for e in relevant_confluence],
-            },
-            recommendations=compliance.recommendations,
-        )
-```
-### 5.2 Confluence Documentation Analysis
-```python
-class ConfluenceDocumentationAnalyzer:
-    """Analyze Confluence documentation for project."""
-    REQUIRED_DOCUMENTATION = {
-        "architecture": {
-            "patterns": ["architecture", "design", "overview", "system-design"],
-            "weight": 2.0,
-            "required_sections": ["overview", "components", "data-flow"],
-        },
-        "api": {
-            "patterns": ["api", "api-reference", "endpoints", "swagger"],
-            "weight": 2.0,
-            "required_sections": ["authentication", "endpoints", "examples"],
-        },
-        "deployment": {
-            "patterns": ["deployment", "runbook", "operations", "devops"],
-            "weight": 1.5,
-            "required_sections": ["prerequisites", "steps", "rollback"],
-        },
-        "security": {
-            "patterns": ["security", "guidelines", "threat-model"],
-            "weight": 2.0,
-            "required_sections": ["authentication", "authorization", "data-protection"],
-        },
-        "onboarding": {
-            "patterns": ["onboarding", "getting-started", "developer-guide"],
-            "weight": 1.0,
-            "required_sections": ["setup", "development", "testing"],
-        },
-    }
-    async def analyze(
-        self,
-        space_key: str,
-        project_name: str,
-    ) -> DocumentationScore:
-        """Analyze Confluence documentation completeness and quality."""
-        # 1. Get all pages in space
-        all_pages = await self.client.get_space_pages(space_key)
-        # 2. Find required documentation pages
-        found_pages = {}
-        missing_pages = []
-        for doc_type, config in self.REQUIRED_DOCUMENTATION.items():
-            page = self._find_matching_page(all_pages, config["patterns"], project_name)
-            if page:
-                content = await self.client.get_page_content(page.id)
-                analysis = self._analyze_page(content, config["required_sections"])
-                found_pages[doc_type] = {
-                    "page": page,
-                    "content": content,
-                    "analysis": analysis,
-                    "score": self._score_page(analysis, config),
-                }
-            else:
-                missing_pages.append(doc_type)
-        # 3. Calculate overall documentation score
-        total_weight = sum(c["weight"] for c in self.REQUIRED_DOCUMENTATION.values())
-        weighted_score = sum(
-            found_pages[doc]["score"] * self.REQUIRED_DOCUMENTATION[doc]["weight"]
-            for doc in found_pages
-        )
-        overall_score = (weighted_score / total_weight) * 10 if total_weight > 0 else 0
-        # 4. Generate recommendations
-        recommendations = self._generate_recommendations(found_pages, missing_pages)
-        return DocumentationScore(
-            overall_score=overall_score,
-            maturity_level=MaturityLevel.from_score(overall_score),
-            page_scores={doc: data["score"] for doc, data in found_pages.items()},
-            required_pages_found=list(found_pages.keys()),
-            required_pages_missing=missing_pages,
-            coverage_percentage=len(found_pages) / len(self.REQUIRED_DOCUMENTATION) * 100,
-            recommendations=recommendations,
-        )
-    def _analyze_page(
-        self,
-        content: str,
-        required_sections: list[str],
-    ) -> PageAnalysis:
-        """Analyze page content quality."""
-        soup = BeautifulSoup(content, "html.parser")
-        text = soup.get_text()
-        headings = [h.text.lower() for h in soup.find_all(["h1", "h2", "h3"])]
-        # Check required sections
-        sections_found = [
-            section for section in required_sections
-            if any(section in h for h in headings)
-        ]
-        return PageAnalysis(
-            word_count=len(text.split()),
-            heading_count=len(headings),
-            headings=headings,
-            code_blocks=len(soup.find_all(["code", "pre"])),
-            tables=len(soup.find_all("table")),
-            images=len(soup.find_all("img")),
-            links=len(soup.find_all("a")),
-            required_sections=required_sections,
-            sections_found=sections_found,
-            sections_missing=[s for s in required_sections if s not in sections_found],
-        )
-    def _score_page(self, analysis: PageAnalysis, config: dict) -> float:
-        """Score page quality 0-10."""
-        score = 0.0
-        # Section coverage (0-4 pts)
-        section_ratio = len(analysis.sections_found) / len(analysis.required_sections)
-        score += section_ratio * 4.0
-        # Content depth (0-3 pts)
-        if analysis.word_count >= 1000:
-            score += 3.0
-        elif analysis.word_count >= 500:
-            score += 2.0
-        elif analysis.word_count >= 200:
-            score += 1.0
-        # Quality indicators (0-3 pts)
-        if analysis.code_blocks >= 2:
-            score += 1.0
-        if analysis.tables >= 1:
-            score += 0.5
-        if analysis.images >= 1:
-            score += 0.5
-        if analysis.links >= 5:
-            score += 0.5
-        if len(analysis.headings) >= 5:
-            score += 0.5
-        return min(10.0, score)
-```
----
-## 6. Score Aggregation
-### 6.1 Project-Level Aggregation
-```python
-class ProjectScoreAggregator:
-    """Aggregate scores across multiple repositories."""
-    def aggregate(
-        self,
-        repo_results: list[RepositoryAuditResult],
-        doc_score: DocumentationScore,
-        template: AuditTemplate,
-    ) -> ProjectAuditResult:
-        """Aggregate all repository results into project score."""
-        # 1. Calculate section aggregates
-        section_aggregates = self._aggregate_sections(repo_results, template)
-        # 2. Calculate repository scores
-        repo_scores = {r.repository_name: r.overall_score for r in repo_results}
-        # 3. Calculate overall project score
-        # Weight: 70% code (repos), 30% documentation (Confluence)
-        avg_repo_score = sum(repo_scores.values()) / len(repo_scores) if repo_scores else 0
-        overall_score = (avg_repo_score * 0.7) + (doc_score.overall_score * 0.3)
-        # 4. Determine overall maturity (conservative: minimum)
-        all_maturities = [r.maturity_level for r in repo_results] + [doc_score.maturity_level]
-        overall_maturity = min(all_maturities, key=lambda m: m.value)
-        # 5. Identify cross-repo findings
-        cross_repo_findings = self._identify_cross_repo_issues(repo_results)
-        return ProjectAuditResult(
-            overall_score=overall_score,
-            overall_grade=self._calculate_grade(overall_score, overall_maturity),
-            overall_maturity=overall_maturity,
-            repository_results=repo_results,
-            section_aggregates=section_aggregates,
-            documentation_score=doc_score,
-            cross_repo_findings=cross_repo_findings,
-            total_repos=len(repo_results),
-            repos_passed=sum(1 for r in repo_results if r.overall_score >= 6.0),
-            repos_failed=sum(1 for r in repo_results if r.overall_score < 6.0),
-        )
-    def _aggregate_sections(
-        self,
-        repo_results: list[RepositoryAuditResult],
-        template: AuditTemplate,
-    ) -> list[SectionAggregate]:
-        """Aggregate section scores across all repos."""
-        aggregates = []
-        for section in template.sections:
-            # Collect scores for this section from all repos
-            repo_scores = {}
-            maturity_counts = {level: 0 for level in MaturityLevel}
-            for repo_result in repo_results:
-                section_result = next(
-                    (s for s in repo_result.sections if s.section_id == section.id),
-                    None
-                )
-                if section_result and section_result.status != CheckStatus.NOT_APPLICABLE:
-                    repo_scores[repo_result.repository_name] = section_result.score_percentage
-                    maturity_counts[section_result.maturity_level] += 1
-            if not repo_scores:
-                continue
-            scores = list(repo_scores.values())
-            aggregates.append(SectionAggregate(
-                section_id=section.id,
-                section_name=section.name,
-                weight=section.weight,
-                average_score=sum(scores) / len(scores),
-                min_score=min(scores),
-                max_score=max(scores),
-                median_score=sorted(scores)[len(scores) // 2],
-                repo_scores=repo_scores,
-                maturity_distribution=maturity_counts,
-            ))
-        return aggregates
-    def _identify_cross_repo_issues(
-        self,
-        repo_results: list[RepositoryAuditResult],
-    ) -> list[CrossRepoFinding]:
-        """Identify issues that appear across multiple repos."""
-        # Count issue occurrences across repos
-        issue_counts: dict[str, list[str]] = {}
-        for repo_result in repo_results:
-            for section in repo_result.sections:
-                for finding in section.findings:
-                    if finding.status in [CheckStatus.FAIL, CheckStatus.WARNING]:
-                        issue_key = f"{finding.check_id}:{finding.status}"
-                        if issue_key not in issue_counts:
-                            issue_counts[issue_key] = []
-                        issue_counts[issue_key].append(repo_result.repository_name)
-        # Create cross-repo findings for issues in multiple repos
-        cross_findings = []
-        for issue_key, repos in issue_counts.items():
-            if len(repos) >= 2:  # Issue in 2+ repos
-                check_id, status = issue_key.split(":")
-                cross_findings.append(CrossRepoFinding(
-                    check_id=check_id,
-                    issue_type=status,
-                    affected_repos=repos,
-                    occurrence_rate=len(repos) / len(repo_results),
-                    recommendation=f"Systemic issue in {len(repos)} repos - consider project-wide remediation",
-                ))
-        return sorted(cross_findings, key=lambda f: -f.occurrence_rate)
-```
----
-## 7. CLI Integration
-### 7.1 Updated CLI Commands
-```bash
-# Audit one repo or a directory of repos
-vds-audit audit /path/to/repos \
-  --template audit_template.xlsx \
-  --concurrency 5 \
-  --output audit_report.xlsx
-# Google Sheets template
-vds-audit audit /path/to/repos \
-  --template-url "https://docs.google.com/spreadsheets/d/..." \
-  --template-sheet "Checklist" \
-  --template-map rubric_mapping.json
-# Include gap analysis in reports
-vds-audit audit /path/to/repos \
-  --template audit_template.xlsx \
-  --gap-analysis \
-  --gap-llm-model "claude-sonnet-4-20250514"
-```
-### 7.2 Example Usage
-```bash
-# Full audit with a template file
-vds-audit audit /path/to/repos \
-  --template /path/to/insurance_audit_template.xlsx
-# Audit a single repo
-vds-audit audit /path/to/ins-api-gateway \
-  --template /path/to/template.xlsx
-# Google Sheets template
-vds-audit audit /path/to/repos \
-  --template "https://docs.google.com/spreadsheets/d/1abc.../edit" \
-  --template-sheet "Checklist"
-# Include gap analysis
-vds-audit audit /path/to/repos \
-  --template /path/to/template.xlsx \
-  --gap-analysis
-```
----
-## 8. Report Structure
-### 8.1 Project Audit Report
-```
-reports/
-└── INSURANCE-project_2026-01-31/
-    ├── summary.json                    # Full JSON report
-    ├── summary.md                      # Markdown summary
-    ├── summary.xlsx                    # Excel with all data
-    │
-    ├── repositories/                   # Per-repo details
-    │   ├── ins-api-gateway.json
-    │   ├── ins-api-gateway.md
-    │   ├── ins-policy-service.json
-    │   ├── ins-policy-service.md
-    │   └── ...
-    │
-    ├── documentation/                  # Confluence analysis
-    │   ├── documentation_score.json
-    │   └── documentation_score.md
-    │
-    └── sarif/                          # SARIF for CI/CD
-        ├── ins-api-gateway.sarif
-        ├── ins-policy-service.sarif
-        └── ...
-```
-### 8.2 Summary Report Structure
-```json
-{
-  "project": {
-    "key": "INSURANCE-project",
-    "name": "Insurance Platform",
-    "audit_date": "2026-01-31T10:30:00Z"
-  },
-  "overall": {
-    "score": 7.2,
-    "grade": "B",
-    "maturity": "MANAGED",
-    "repos_audited": 7,
-    "repos_passed": 5,
-    "repos_failed": 2
-  },
-  "score_breakdown": {
-    "code_quality": { "average": 7.5, "min": 5.2, "max": 9.1 },
-    "documentation": { "average": 6.8, "min": 4.0, "max": 8.5 },
-    "security": { "average": 7.8, "min": 6.5, "max": 9.0 },
-    "testing": { "average": 6.5, "min": 3.2, "max": 8.8 },
-    "ci_cd": { "average": 8.2, "min": 7.0, "max": 9.5 }
-  },
-  "documentation_score": {
-    "overall": 7.0,
-    "architecture_docs": 8.5,
-    "api_docs": 6.0,
-    "deployment_docs": 7.5,
-    "security_docs": 6.0,
-    "missing": ["onboarding"]
-  },
-  "repositories": [
-    {
-      "name": "ins-api-gateway",
-      "type": "gateway",
-      "score": 8.2,
-      "grade": "A",
-      "maturity": "MANAGED"
-    },
-    {
-      "name": "ins-policy-service",
-      "type": "service",
-      "score": 7.5,
-      "grade": "B+",
-      "maturity": "DEFINED"
-    }
-  ],
-  "cross_repo_issues": [
-    {
-      "issue": "Missing CHANGELOG.md",
-      "affected_repos": ["ins-claim-service", "ins-notification-service"],
-      "recommendation": "Add CHANGELOG.md to all repositories"
-    }
-  ],
-  "top_recommendations": [
-    "Add API documentation to Confluence",
-    "Improve test coverage in ins-claim-service (currently 45%)",
-    "Add security scanning to CI/CD in 3 repositories"
-  ]
-}
-```
----
-## 9. Implementation Roadmap
-| Phase | Sprint | Focus | Deliverables |
-|-------|--------|-------|--------------|
-| **1** | 1-2 | Multi-Repo Infrastructure | RepositoryDiscovery, RepoType classification, parallel processing |
-| **2** | 3 | Confluence Integration | ConfluenceDocumentationAnalyzer, page quality scoring |
-| **3** | 4 | Content Analysis | RequirementAnalyzer, SemanticMatcher, CodeEvidenceCollector |
-| **4** | 5 | Score Aggregation | ProjectScoreAggregator, cross-repo findings |
-| **5** | 6 | CLI & Reports | Updated CLI, project-level reports |
----
-## 10. References
-- [GitHub Multi-Repository Scanning](https://github.blog/news-insights/product-news/multi-repository-enablement-effortlessly-scale-code-scanning-across-your-repositories/)
-- [Monorepo Code Scanning Action](https://github.com/advanced-security/monorepo-code-scanning-action)
-- [Enterprise Audit Checklist Best Practices](https://flevy.com)
-- [Compliance Automation - CSA](https://cloudsecurityalliance.org/blog/2025/04/29/a-new-era-for-compliance-introducing-the-compliance-automation-revolution-car)
-- [SentinelOne Code Security Audit Guide](https://www.sentinelone.com/cybersecurity-101/cybersecurity/code-security-audit/)