Developer Guide

agentready/
├── src/agentready/          # Source code
│   ├── cli/                 # Click-based CLI
│   │   └── main.py          # Entry point (assess, research-version, generate-config)
│   ├── models/              # Data models
│   │   ├── repository.py    # Repository representation
│   │   ├── attribute.py     # Attribute definition
│   │   ├── finding.py       # Assessment finding
│   │   └── assessment.py    # Complete assessment result
│   ├── services/            # Core business logic
│   │   ├── scanner.py       # Assessment orchestration
│   │   ├── scorer.py        # Score calculation
│   │   └── language_detector.py  # Language detection via git
│   ├── assessors/           # Attribute assessors
│   │   ├── base.py          # BaseAssessor abstract class
│   │   ├── documentation.py # CLAUDE.md, README assessors
│   │   ├── code_quality.py  # Type annotations, complexity
│   │   ├── testing.py       # Test coverage, pre-commit hooks
│   │   ├── structure.py     # Standard layout, gitignore
│   │   ├── repomix.py       # Repomix configuration assessor
│   │   └── stub_assessors.py # 9 stub assessors (22 implemented)
│   ├── reporters/           # Report generators
│   │   ├── html.py          # Interactive HTML with Jinja2
│   │   ├── markdown.py      # GitHub-Flavored Markdown
│   │   └── json.py          # Machine-readable JSON
│   ├── templates/           # Jinja2 templates
│   │   └── report.html.j2   # HTML report template
│   └── data/                # Bundled data
│       └── attributes.yaml  # Attribute definitions
├── tests/                   # Test suite
│   ├── unit/               # Unit tests (fast, isolated)
│   │   ├── test_models.py
│   │   ├── test_assessors_documentation.py
│   │   ├── test_assessors_code_quality.py
│   │   └── ...
│   ├── integration/        # End-to-end tests
│   │   └── test_full_assessment.py
│   └── fixtures/           # Test data
│       └── sample_repos/   # Sample repositories for testing
├── docs/                    # GitHub Pages documentation
├── examples/               # Example reports
│   └── self-assessment/    # AgentReady's own assessment
├── pyproject.toml          # Python package configuration
├── CLAUDE.md              # Project context for AI agents
├── README.md              # User-facing documentation
└── BACKLOG.md             # Feature backlog

Repository → Scanner → Assessors → Findings → Assessment → Reporters → Reports
                ↓
         Language Detection
         (git ls-files)

from abc import ABC, abstractmethod

class BaseAssessor(ABC):
    @property
    @abstractmethod
    def attribute_id(self) -> str:
        """Unique attribute identifier."""
        pass

    @abstractmethod
    def assess(self, repository: Repository) -> Finding:
        """Assess repository for this attribute."""
        pass

    def is_applicable(self, repository: Repository) -> bool:
        """Check if this assessor applies to the repository."""
        return True

# Pass with full score
finding = Finding.create_pass(
    attribute=attribute,
    evidence="Found CLAUDE.md at repository root",
    remediation=None
)

# Fail with zero score
finding = Finding.create_fail(
    attribute=attribute,
    evidence="No CLAUDE.md file found",
    remediation=Remediation(steps=[...], tools=[...])
)

# Skip (not applicable)
finding = Finding.create_skip(
    attribute=attribute,
    reason="Not implemented yet"
)

from jinja2 import Environment, FileSystemLoader

class HTMLReporter:
    def generate(self, assessment: Assessment) -> str:
        env = Environment(loader=FileSystemLoader('templates'))
        template = env.get_template('report.html.j2')
        return template.render(assessment=assessment)

Repository → LanguageDetector → BootstrapGenerator → Templates → Generated Files
                     ↓                    ↓
              Primary Language    Template Variables
                                   (language, repo_name, etc.)

class BootstrapGenerator:
    """Generate agent-ready infrastructure for repositories."""

    def __init__(self, template_dir: str):
        """Initialize with template directory path."""
        self.template_dir = template_dir
        self.jinja_env = Environment(loader=FileSystemLoader(template_dir))

    def generate(
        self,
        repository: Repository,
        language: str = "auto",
        dry_run: bool = False
    ) -> List[GeneratedFile]:
        """
        Generate infrastructure files for repository.

        Args:
            repository: Repository object
            language: Primary language (auto-detected if "auto")
            dry_run: Preview only, don't create files

        Returns:
            List of GeneratedFile objects with paths and content
        """

@click.command()
@click.argument("repository", type=click.Path(exists=True), default=".")
@click.option("--dry-run", is_flag=True, help="Preview without creating files")
@click.option(
    "--language",
    type=click.Choice(["python", "javascript", "go", "auto"]),
    default="auto",
    help="Primary language override"
)
def bootstrap(repository, dry_run, language):
    """Bootstrap agent-ready infrastructure for repository."""

templates/bootstrap/
├── common/                          # Language-agnostic templates
│   ├── CODEOWNERS.j2
│   ├── CONTRIBUTING.md.j2
│   ├── CODE_OF_CONDUCT.md.j2
│   ├── bug_report.md.j2
│   ├── feature_request.md.j2
│   └── pull_request_template.md.j2
├── python/                          # Python-specific
│   ├── agentready-assessment.yml.j2
│   ├── tests.yml.j2
│   ├── security.yml.j2
│   ├── pre-commit-config.yaml.j2
│   └── dependabot.yml.j2
├── javascript/                      # JavaScript-specific
│   └── ... (similar structure)
└── go/                              # Go-specific
    └── ... (similar structure)

context = {
    "repository_name": repository.name,
    "language": detected_language,
    "has_tests_directory": os.path.exists(f"{repo_path}/tests"),
    "has_src_directory": os.path.exists(f"{repo_path}/src"),
    "python_version": "3.11",  # Or detected version
    "node_version": "18",      # Or detected version
    "go_version": "1.21",      # Or detected version
    "year": datetime.now().year,
    "organization": extract_org_from_remote(repo_path)  # From git remote
}

class LanguageDetector:
    """Detect primary language from repository files."""

    EXTENSION_MAP = {
        ".py": "Python",
        ".js": "JavaScript",
        ".ts": "TypeScript",
        ".go": "Go",
        ".java": "Java",
        # ... more extensions
    }

    def detect(self, repo_path: str) -> Dict[str, int]:
        """
        Count files by language.

        Returns:
            Dict mapping language name to file count
            Example: {"Python": 42, "JavaScript": 18}
        """

    def get_primary_language(self, languages: Dict[str, int]) -> str:
        """Return language with most files."""
        return max(languages, key=languages.get)

class BootstrapError(Exception):
    """Base exception for Bootstrap errors."""

class LanguageDetectionError(BootstrapError):
    """Raised when language detection fails."""

class TemplateRenderError(BootstrapError):
    """Raised when template rendering fails."""

class FileWriteError(BootstrapError):
    """Raised when file write fails (permissions, etc.)."""

def generate(self, repository, language="auto", dry_run=False):
    """Generate infrastructure."""

    generated_files = []

    for template_path in templates:
        content = self._render_template(template_path, context)
        output_path = self._determine_output_path(template_path)

        if dry_run:
            # Don't write, just report what would happen
            generated_files.append(
                GeneratedFile(
                    path=output_path,
                    content=content,
                    created=False,  # Would be created
                    dry_run=True
                )
            )
        else:
            if not os.path.exists(output_path):
                self._write_file(output_path, content)
                generated_files.append(
                    GeneratedFile(
                        path=output_path,
                        content=content,
                        created=True
                    )
                )

    return generated_files

# Example stub assessor
class InlineDocumentationAssessor(BaseAssessor):
    @property
    def attribute_id(self) -> str:
        return "inline_documentation"

    def assess(self, repository: Repository) -> Finding:
        # TODO: Implement actual assessment logic
        return Finding.create_skip(
            self.attribute,
            reason="Assessor not yet implemented"
        )

# src/agentready/assessors/documentation.py

from agentready.models import Repository, Finding, Attribute, Remediation
from agentready.assessors.base import BaseAssessor

class InlineDocumentationAssessor(BaseAssessor):
    @property
    def attribute_id(self) -> str:
        return "inline_documentation"

    def assess(self, repository: Repository) -> Finding:
        """
        Assess inline documentation coverage (docstrings/JSDoc).

        Checks:
        - Python: Presence of docstrings in .py files
        - JavaScript/TypeScript: JSDoc comments
        - Coverage: >80% of public functions documented
        """
        # Implement assessment logic here
        pass

def assess(self, repository: Repository) -> Finding:
    # Example: Check Python docstrings
    if "Python" not in repository.languages:
        return Finding.create_skip(
            self.attribute,
            reason="No Python files detected"
        )

    # Count functions and docstrings
    total_functions = self._count_functions(repository)
    documented_functions = self._count_documented_functions(repository)

    if total_functions == 0:
        return Finding.create_skip(
            self.attribute,
            reason="No functions found"
        )

    # Calculate coverage
    coverage = documented_functions / total_functions
    score = self.calculate_proportional_score(coverage, 0.80)

    if score >= 80:  # Passes if >= 80% of target
        return Finding.create_pass(
            self.attribute,
            evidence=f"Documented {documented_functions}/{total_functions} functions ({coverage:.1%})",
            remediation=None
        )
    else:
        return Finding.create_fail(
            self.attribute,
            evidence=f"Only {documented_functions}/{total_functions} functions documented ({coverage:.1%})",
            remediation=self._create_remediation(coverage)
        )

def _count_functions(self, repository: Repository) -> int:
    """Count total functions in Python files."""
    # Implementation using ast or grep
    pass

def _count_documented_functions(self, repository: Repository) -> int:
    """Count functions with docstrings."""
    # Implementation using ast
    pass

def _create_remediation(self, current_coverage: float) -> Remediation:
    """Generate remediation guidance."""
    return Remediation(
        steps=[
            "Install pydocstyle: `pip install pydocstyle`",
            "Run docstring linter: `pydocstyle src/`",
            "Add docstrings to flagged functions",
            f"Target: {(0.80 - current_coverage) * 100:.0f}% more functions need documentation"
        ],
        tools=["pydocstyle", "pylint"],
        commands=[
            "pydocstyle src/",
            "pylint --disable=all --enable=missing-docstring src/"
        ],
        examples=[
            '''def calculate_total(items: List[Item]) -> float:
    """
    Calculate total price of items.

    Args:
        items: List of items to sum

    Returns:
        Total price in USD

    Example:
        >>> calculate_total([Item(5.0), Item(3.0)])
        8.0
    """
    return sum(item.price for item in items)'''
        ],
        citations=[
            "PEP 257 - Docstring Conventions",
            "Google Python Style Guide"
        ]
    )

def __init__(self):
    self.assessors = [
        # Existing assessors...
        InlineDocumentationAssessor(),
    ]

import pytest
from agentready.models import Repository
from agentready.assessors.documentation import InlineDocumentationAssessor

class TestInlineDocumentationAssessor:
    def test_python_well_documented_passes(self, tmp_path):
        """Well-documented Python code should pass."""
        # Create test repository
        repo_path = tmp_path / "test_repo"
        repo_path.mkdir()
        (repo_path / ".git").mkdir()

        # Create Python file with docstrings
        code = '''
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

def subtract(a: int, b: int) -> int:
    """Subtract b from a."""
    return a - b
'''
        (repo_path / "main.py").write_text(code)

        # Create repository object
        repo = Repository(
            path=str(repo_path),
            name="test_repo",
            languages={"Python": 1}
        )

        # Run assessment
        assessor = InlineDocumentationAssessor()
        finding = assessor.assess(repo)

        # Verify result
        assert finding.status == "pass"
        assert finding.score == 100
        assert "2/2 functions" in finding.evidence

    def test_python_poorly_documented_fails(self, tmp_path):
        """Poorly documented Python code should fail."""
        # Create test repository
        repo_path = tmp_path / "test_repo"
        repo_path.mkdir()
        (repo_path / ".git").mkdir()

        # Create Python file with no docstrings
        code = '''
def add(a, b):
    return a + b

def subtract(a, b):
    return a - b
'''
        (repo_path / "main.py").write_text(code)

        repo = Repository(
            path=str(repo_path),
            name="test_repo",
            languages={"Python": 1}
        )

        assessor = InlineDocumentationAssessor()
        finding = assessor.assess(repo)

        assert finding.status == "fail"
        assert finding.score < 80
        assert "0/2 functions" in finding.evidence
        assert finding.remediation is not None
        assert "pydocstyle" in finding.remediation.tools

    def test_non_python_skips(self, tmp_path):
        """Non-Python repositories should skip."""
        repo = Repository(
            path=str(tmp_path),
            name="test_repo",
            languages={"JavaScript": 10}
        )

        assessor = InlineDocumentationAssessor()
        finding = assessor.assess(repo)

        assert finding.status == "skipped"
        assert "No Python files" in finding.reason

tests/
├── unit/                  # Fast, isolated tests
│   ├── test_models.py
│   ├── test_assessors_*.py
│   └── test_reporters.py
├── integration/           # End-to-end tests
│   └── test_full_assessment.py
└── fixtures/              # Shared test data
    └── sample_repos/

# Good
def test_claude_md_assessor_with_existing_file_passes():
    pass

def test_readme_assessor_missing_quick_start_fails():
    pass

def test_type_annotations_assessor_javascript_repo_skips():
    pass

# Bad
def test_assessor():
    pass

def test_pass_case():
    pass

def test_finding_create_pass_sets_correct_attributes():
    # Arrange
    attribute = Attribute(
        id="test_attr",
        name="Test Attribute",
        tier=1,
        weight=0.10
    )

    # Act
    finding = Finding.create_pass(
        attribute=attribute,
        evidence="Test evidence",
        remediation=None
    )

    # Assert
    assert finding.status == "pass"
    assert finding.score == 100
    assert finding.evidence == "Test evidence"
    assert finding.remediation is None

@pytest.fixture
def sample_repository(tmp_path):
    """Create a sample repository for testing."""
    repo_path = tmp_path / "sample_repo"
    repo_path.mkdir()
    (repo_path / ".git").mkdir()

    # Add files
    (repo_path / "README.md").write_text("# Sample Repo")
    (repo_path / "CLAUDE.md").write_text("# Tech Stack")

    return Repository(
        path=str(repo_path),
        name="sample_repo",
        languages={"Python": 5}
    )

def test_with_fixture(sample_repository):
    assert sample_repository.name == "sample_repo"

def calculate_weighted_score(findings: List[Finding], weights: Dict[str, float]) -> float:
    """
    Calculate weighted average score from findings.

    Args:
        findings: List of assessment findings
        weights: Attribute ID to weight mapping

    Returns:
        Weighted score from 0.0 to 100.0

    Raises:
        ValueError: If weights don't sum to 1.0

    Example:
        >>> findings = [Finding(score=80), Finding(score=90)]
        >>> weights = {"attr1": 0.5, "attr2": 0.5}
        >>> calculate_weighted_score(findings, weights)
        85.0
    """
    pass