feat: Implement CICDPipelineVisibilityAssessor (fixes #85)

Author: jeremyeder

src/agentready/assessors/testing.py

@@ -1,5 +1,8 @@
 """Testing assessors for test coverage, naming conventions, and pre-commit hooks."""
 
+import re
+from pathlib import Path
+
 from ..models.attribute import Attribute
 from ..models.finding import Citation, Finding, Remediation
 from ..models.repository import Repository
@@ -314,3 +317,328 @@ def _create_remediation(self) -> Remediation:
                 )
             ],
         )
+
+
+class CICDPipelineVisibilityAssessor(BaseAssessor):
+    """Assesses CI/CD pipeline configuration visibility and quality.
+
+    Tier 3 Important (1.5% weight) - Clear CI/CD configs enable AI to understand
+    build/test/deploy processes and suggest improvements.
+    """
+
+    @property
+    def attribute_id(self) -> str:
+        return "cicd_pipeline_visibility"
+
+    @property
+    def tier(self) -> int:
+        return 3  # Important
+
+    @property
+    def attribute(self) -> Attribute:
+        return Attribute(
+            id=self.attribute_id,
+            name="CI/CD Pipeline Visibility",
+            category="Testing & CI/CD",
+            tier=self.tier,
+            description="Clear, well-documented CI/CD configuration files",
+            criteria="CI config with descriptive names, caching, parallelization",
+            default_weight=0.015,
+        )
+
+    def assess(self, repository: Repository) -> Finding:
+        """Check for CI/CD configuration and assess quality.
+
+        Scoring:
+        - CI config exists (50%)
+        - Config quality (30%): descriptive names, caching, parallelization
+        - Best practices (20%): comments, artifacts
+        """
+        # Check for CI config files
+        ci_configs = self._detect_ci_configs(repository)
+
+        if not ci_configs:
+            return Finding(
+                attribute=self.attribute,
+                status="fail",
+                score=0.0,
+                measured_value="no CI config",
+                threshold="CI config present",
+                evidence=[
+                    "No CI/CD configuration found",
+                    "Checked: GitHub Actions, GitLab CI, CircleCI, Travis CI",
+                ],
+                remediation=self._create_remediation(),
+                error_message=None,
+            )
+
+        # Score: CI exists (50%)
+        score = 50
+        evidence = [
+            f"CI config found: {', '.join(str(c.relative_to(repository.path)) for c in ci_configs)}"
+        ]
+
+        # Analyze first CI config for quality
+        primary_config = ci_configs[0]
+        quality_score, quality_evidence = self._assess_config_quality(primary_config)
+        score += quality_score
+        evidence.extend(quality_evidence)
+
+        status = "pass" if score >= 75 else "fail"
+
+        return Finding(
+            attribute=self.attribute,
+            status=status,
+            score=score,
+            measured_value=(
+                "configured with best practices" if score >= 75 else "basic config"
+            ),
+            threshold="CI with best practices",
+            evidence=evidence,
+            remediation=self._create_remediation() if status == "fail" else None,
+            error_message=None,
+        )
+
+    def _detect_ci_configs(self, repository: Repository) -> list:
+        """Detect CI/CD configuration files."""
+        ci_config_checks = [
+            repository.path / ".github" / "workflows",  # GitHub Actions (directory)
+            repository.path / ".gitlab-ci.yml",  # GitLab CI
+            repository.path / ".circleci" / "config.yml",  # CircleCI
+            repository.path / ".travis.yml",  # Travis CI
+            repository.path / "Jenkinsfile",  # Jenkins
+        ]
+
+        configs = []
+        for config_path in ci_config_checks:
+            if config_path.exists():
+                if config_path.is_dir():
+                    # GitHub Actions: check for workflow files
+                    workflow_files = list(config_path.glob("*.yml")) + list(
+                        config_path.glob("*.yaml")
+                    )
+                    if workflow_files:
+                        configs.extend(workflow_files)
+                else:
+                    configs.append(config_path)
+
+        return configs
+
+    def _assess_config_quality(self, config_file: Path) -> tuple:
+        """Assess quality of CI config file.
+
+        Returns:
+            Tuple of (quality_score, evidence_list)
+            quality_score: 0-50 (30 for quality checks + 20 for best practices)
+        """
+        try:
+            content = config_file.read_text()
+        except OSError:
+            return (0, ["Could not read CI config file"])
+
+        quality_score = 0
+        evidence = []
+
+        # Quality checks (30 points total)
+        # Descriptive job/step names (10 points)
+        if self._has_descriptive_names(content):
+            quality_score += 10
+            evidence.append("Descriptive job/step names found")
+        else:
+            evidence.append("Generic job names (consider more descriptive names)")
+
+        # Caching configured (10 points)
+        if self._has_caching(content):
+            quality_score += 10
+            evidence.append("Caching configured")
+        else:
+            evidence.append("No caching detected")
+
+        # Parallelization (10 points)
+        if self._has_parallelization(content):
+            quality_score += 10
+            evidence.append("Parallel job execution detected")
+        else:
+            evidence.append("No parallelization detected")
+
+        # Best practices (20 points total)
+        # Comments in config (10 points)
+        if self._has_comments(content):
+            quality_score += 10
+            evidence.append("Config includes comments")
+
+        # Artifact uploading (10 points)
+        if self._has_artifacts(content):
+            quality_score += 10
+            evidence.append("Artifacts uploaded")
+
+        return (quality_score, evidence)
+
+    def _has_descriptive_names(self, content: str) -> bool:
+        """Check for descriptive job/step names (not just 'build', 'test')."""
+        # Look for name fields with descriptive text (>2 words or specific actions)
+        descriptive_patterns = [
+            r'name:\s*["\']?[A-Z][^"\'\n]{20,}',  # Long descriptive names
+            r'name:\s*["\']?(?:Run|Build|Deploy|Install|Lint|Format|Check)\s+\w+',  # Action + context
+        ]
+
+        return any(
+            re.search(pattern, content, re.IGNORECASE)
+            for pattern in descriptive_patterns
+        )
+
+    def _has_caching(self, content: str) -> bool:
+        """Check for caching configuration."""
+        cache_patterns = [
+            r'cache:\s*["\']?(pip|npm|yarn|maven|gradle)',  # GitLab/CircleCI style
+            r"actions/cache@",  # GitHub Actions cache action
+            r"with:\s*\n\s*cache:",  # GitHub Actions setup with cache
+        ]
+
+        return any(
+            re.search(pattern, content, re.IGNORECASE) for pattern in cache_patterns
+        )
+
+    def _has_parallelization(self, content: str) -> bool:
+        """Check for parallel job execution."""
+        parallel_patterns = [
+            r"jobs:\s*\n\s+\w+:\s*\n.*\n\s+\w+:",  # Multiple jobs defined
+            r"matrix:",  # Matrix strategy
+            r"parallel:\s*\d+",  # Explicit parallelization
+        ]
+
+        return any(
+            re.search(pattern, content, re.DOTALL) for pattern in parallel_patterns
+        )
+
+    def _has_comments(self, content: str) -> bool:
+        """Check for explanatory comments in config."""
+        # Look for YAML comments
+        comment_lines = [
+            line for line in content.split("\n") if line.strip().startswith("#")
+        ]
+        # Filter out just shebang or empty comments
+        meaningful_comments = [c for c in comment_lines if len(c.strip()) > 2]
+
+        return len(meaningful_comments) >= 3  # At least 3 meaningful comments
+
+    def _has_artifacts(self, content: str) -> bool:
+        """Check for artifact uploading."""
+        artifact_patterns = [
+            r"actions/upload-artifact@",  # GitHub Actions
+            r"artifacts:",  # GitLab CI
+            r"store_artifacts:",  # CircleCI
+        ]
+
+        return any(re.search(pattern, content) for pattern in artifact_patterns)
+
+    def _create_remediation(self) -> Remediation:
+        """Create remediation guidance for CI/CD visibility."""
+        return Remediation(
+            summary="Add or improve CI/CD pipeline configuration",
+            steps=[
+                "Create CI config for your platform (GitHub Actions, GitLab CI, etc.)",
+                "Define jobs: lint, test, build",
+                "Use descriptive job and step names",
+                "Configure dependency caching",
+                "Enable parallel job execution",
+                "Upload artifacts: test results, coverage reports",
+                "Add status badge to README",
+            ],
+            tools=["github-actions", "gitlab-ci", "circleci"],
+            commands=[
+                "# Create GitHub Actions workflow",
+                "mkdir -p .github/workflows",
+                "touch .github/workflows/ci.yml",
+                "",
+                "# Validate workflow",
+                "gh workflow view ci.yml",
+            ],
+            examples=[
+                """# .github/workflows/ci.yml - Good example
+
+name: CI Pipeline
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint Code
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'  # Caching
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Run linters
+        run: |
+          black --check .
+          isort --check .
+          ruff check .
+
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Run tests with coverage
+        run: pytest --cov --cov-report=xml
+
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage.xml
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: [lint, test]  # Runs after lint/test pass
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: dist
+          path: dist/
+""",
+            ],
+            citations=[
+                Citation(
+                    source="GitHub",
+                    title="GitHub Actions Documentation",
+                    url="https://docs.github.com/en/actions",
+                    relevance="Official GitHub Actions guide",
+                ),
+                Citation(
+                    source="CircleCI",
+                    title="CI/CD Best Practices",
+                    url="https://circleci.com/blog/ci-cd-best-practices/",
+                    relevance="Industry best practices for CI/CD",
+                ),
+            ],
+        )

src/agentready/cli/main.py

@@ -34,7 +34,11 @@
     LockFilesAssessor,
     create_stub_assessors,
 )
-from ..assessors.testing import PreCommitHooksAssessor, TestCoverageAssessor
+from ..assessors.testing import (
+    CICDPipelineVisibilityAssessor,
+    PreCommitHooksAssessor,
+    TestCoverageAssessor,
+)
 from ..models.config import Config
 from ..reporters.html import HTMLReporter
 from ..reporters.markdown import MarkdownReporter
@@ -78,9 +82,10 @@ def create_all_assessors():
         GitignoreAssessor(),
         OneCommandSetupAssessor(),
         CyclomaticComplexityAssessor(),  # Actually Tier 3, but including here
-        # Tier 3 Important (2 implemented)
+        # Tier 3 Important (4 implemented)
         ArchitectureDecisionsAssessor(),
         IssuePRTemplatesAssessor(),
+        CICDPipelineVisibilityAssessor(),
     ]
 
     # Add remaining stub assessors

src/agentready/cli/research.py

@@ -154,12 +154,8 @@ def init(output, template):
 @click.argument("report_path", type=click.Path(exists=True))
 @click.option("--attribute-id", required=True, help="Attribute ID (e.g., '1.3')")
 @click.option("--name", required=True, help="Attribute name")
-@click.option(
-    "--tier", type=int, required=True, help="Tier assignment (1-4)"
-)
-@click.option(
-    "--category", default="Uncategorized", help="Category name"
-)
+@click.option("--tier", type=int, required=True, help="Tier assignment (1-4)")
+@click.option("--category", default="Uncategorized", help="Category name")
 def add_attribute(report_path, attribute_id, name, tier, category):
     """Add new attribute to research report.
 
@@ -251,9 +247,7 @@ def bump_version(report_path, bump_type, new_version):
 
 @research.command()
 @click.argument("report_path", type=click.Path(exists=True))
-@click.option(
-    "--check", is_flag=True, help="Check formatting without making changes"
-)
+@click.option("--check", is_flag=True, help="Check formatting without making changes")
 @click.option("--verbose", "-v", is_flag=True, help="Show detailed output")
 def format(report_path, check, verbose):
     """Lint and format research report.