feat: Implement OneCommandSetupAssessor

[jeremyeder]

feat: Implement OneCommandSetupAssessor

Attribute Definition

Attribute ID: one_command_setup (Attribute #12 - Tier 2)

Definition: Single command to set up development environment from fresh clone.

Why It Matters: Lengthy setup documentation increases friction and errors. One-command setup enables AI to quickly reproduce environments and test changes. Reduces "works on my machine" problems.

Impact on Agent Behavior:

• Confident environment setup suggestions
• Quick validation of proposed changes
• Easy onboarding recommendations
• Reduced setup-related debugging

Measurable Criteria:

• Single command documented prominently in README
• Examples: make setup, npm install, poetry install, ./bootstrap.sh
• Command handles:
  • Dependency installation
  • Virtual environment creation
  • Database setup/migrations
  • Configuration file creation (.env from .env.example)
  • Pre-commit hooks installation
• Success criteria: Working development environment in <5 minutes
• Idempotent (safe to run multiple times)

Implementation Requirements

File Location: src/agentready/assessors/structure.py

Class Name: OneCommandSetupAssessor

Tier: 2 (Critical)

Default Weight: 0.03 (3% of total score)

Assessment Logic

Scoring Approach: Proportional scoring based on evidence found

Evidence to Check (score components):

1. README contains setup command (40%)

   • Search for keywords: "install", "setup", "bootstrap", "getting started"
   • Look for code blocks with single command
   • Common patterns: make setup, npm install, pip install -e ., poetry install

2. Setup script/Makefile exists (30%)

   • Check for: Makefile, setup.sh, bootstrap.sh, setup.py, package.json
   • Python: setup.py or pyproject.toml
   • JavaScript: package.json with scripts
   • Go: Makefile

3. Documentation clarity (30%)

   • Setup instructions in first 3 sections of README
   • Clear command shown (not buried in long docs)

Scoring Logic:

score = 0
if readme_has_setup_command:
    score += 40
if setup_script_exists:
    score += 30
if setup_in_prominent_location:
    score += 30

# Pass threshold: 75
status = "pass" if score >= 75 else "fail"

Language-Specific Checks:

• Python: pip install -e ., poetry install, uv pip install -e ., make setup
• JavaScript/TypeScript: npm install, yarn install, pnpm install
• Go: make setup, go mod download
• Ruby: bundle install
• Rust: cargo build

Code Pattern to Follow

Reference: StandardLayoutAssessor in structure.py

Pattern:

1. Define attribute metadata
2. Implement assess() method
3. Check multiple evidence sources (README, Makefile, package.json, etc.)
4. Calculate proportional score
5. Provide detailed evidence list
6. Return Finding with remediation if fail

Example Finding Responses

Pass (Score: 100)

Finding(
    attribute=self.attribute,
    status="pass",
    score=100.0,
    measured_value="make setup",
    threshold="single command documented",
    evidence=[
        "Setup command found in README: 'make setup'",
        "Makefile exists with setup target",
        "Setup instructions in prominent location (section 2)",
    ],
    remediation=None,
    error_message=None,
)

Fail (Score: 40)

Finding(
    attribute=self.attribute,
    status="fail",
    score=40.0,
    measured_value="multi-step setup",
    threshold="single command",
    evidence=[
        "README has setup instructions but requires multiple commands",
        "No Makefile or setup script found",
        "Setup requires manual .env configuration",
    ],
    remediation=self._create_remediation(),
    error_message=None,
)

Not Applicable (Score: N/A)

Finding.not_applicable(
    self.attribute,
    reason="No README found, cannot assess setup documentation"
)

Registration

Add to src/agentready/services/scanner.py in create_all_assessors():

from ..assessors.structure import (
    StandardLayoutAssessor,
    GitignoreCompletenessAssessor,
    OneCommandSetupAssessor,  # Add this import
)

def create_all_assessors() -> List[BaseAssessor]:
    return [
        # ... existing assessors ...
        StandardLayoutAssessor(),
        GitignoreCompletenessAssessor(),
        OneCommandSetupAssessor(),  # Add this line
    ]

Testing Guidance

Test File: tests/unit/test_assessors_structure.py

Test Cases to Add:

1. test_one_command_setup_pass_with_makefile: Repository with Makefile and README documenting setup
2. test_one_command_setup_pass_with_package_json: JavaScript project with npm install
3. test_one_command_setup_fail_multi_step: README with multi-step setup
4. test_one_command_setup_fail_no_documentation: No README or setup docs
5. test_one_command_setup_partial_score: Setup script exists but not documented

Note: AgentReady repository has uv pip install -e . as one-command setup, so this attribute should PASS on self-assessment.

Dependencies

External Tools: None (uses built-in file reading)

Python Standard Library:

• pathlib.Path for file checking
• re for regex pattern matching in README

Remediation Steps

def _create_remediation(self) -> Remediation:
    return Remediation(
        summary="Create single-command setup for development environment",
        steps=[
            "Choose setup automation tool (Makefile, setup script, or package manager)",
            "Create setup command that handles all dependencies",
            "Document setup command prominently in README (Quick Start section)",
            "Ensure setup is idempotent (safe to run multiple times)",
            "Test setup on fresh clone to verify it works",
        ],
        tools=["make", "npm", "pip", "poetry"],
        commands=[
            "# Example Makefile",
            "cat > Makefile << 'EOF'",
            ".PHONY: setup",
            "setup:",
            "\tpython -m venv venv",
            "\t. venv/bin/activate && pip install -r requirements.txt",
            "\tpre-commit install",
            "\tcp .env.example .env",
            "\t@echo 'Setup complete! Run make test to verify.'",
            "EOF",
        ],
        examples=[
            """# Quick Start section in README

## Quick Start

```bash
make setup  # One command to set up development environment
make test   # Run tests to verify setup

""",
],
citations=[
Citation(
source="freeCodeCamp",
title="Using make for project automation",
url="https://www.freecodecamp.org/news/want-to-know-the-easiest-way-to-save-time-use-make/",
relevance="Guide to using Makefiles for one-command setup",
),
],
)

## Implementation Notes

1. **README Parsing**: Read README.md and search for setup keywords in first 500 lines
2. **File Existence**: Check for Makefile, setup.sh, package.json, pyproject.toml
3. **Language Detection**: Use `repository.languages` to determine expected setup pattern
4. **Scoring**: Proportional scoring allows partial credit for documented but multi-step setup
5. **Edge Cases**: Handle repositories without README (return not_applicable)

[github-actions]

🎉 This issue has been resolved in version 1.13.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀