diff --git a/submissions/redhat/aipcc-claudio/2026-03-24T17-51-33-assessment.json b/submissions/redhat/aipcc-claudio/2026-03-24T17-51-33-assessment.json new file mode 100644 index 00000000..ff283097 --- /dev/null +++ b/submissions/redhat/aipcc-claudio/2026-03-24T17-51-33-assessment.json @@ -0,0 +1,672 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:51:33.916942", + "assessment_timestamp_human": "March 24, 2026 at 5:51 PM", + "executed_by": "jrusz@a43f21701734", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/ci-cd/aipcc-claudio.git", + "branch": "main", + "commit_hash": "63dd708e4adc5d34ac7bdc69d20af9110a6a9054", + "languages": { + "YAML": 7, + "Markdown": 9 + }, + "total_files": 23, + "total_lines": 3135 + }, + "timestamp": "2026-03-24T17:51:33.916942", + "overall_score": 44.5, + "certification_level": "Bronze", + "attributes_assessed": 11, + "attributes_skipped": 7, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "pass", + "score": 90.0, + "measured_value": "AGENTS.md present", + "threshold": "CLAUDE.md or AGENTS.md", + "evidence": [ + "CLAUDE.md not found", + "AGENTS.md found with 24850 bytes (alternative)", + "Consider adding CLAUDE.md as symlink or @ reference for broader tool support" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "fail", + "score": 66.66666666666666, + "measured_value": "2/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 2/3 essential sections", + "Installation: \u2713", + "Usage: \u2717", + "Development: \u2713" + ], + "remediation": { + "summary": "Create or enhance README.md with essential sections", + "steps": [ + "Add project overview and description", + "Include installation/setup instructions", + "Document basic usage with examples", + "Add development/contributing guidelines", + "Include build and test commands" + ], + "tools": [], + "commands": [], + "examples": [ + "# Project Name\n\n## Overview\nWhat this project does and why it exists.\n\n## Installation\n```bash\npip install -e .\n```\n\n## Usage\n```bash\nmyproject --help\n```\n\n## Development\n```bash\n# Run tests\npytest\n\n# Format code\nblack .\n```\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "About READMEs", + "url": "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes", + "relevance": "Best practices for README structure" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML', 'Markdown']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 0/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py", + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py", + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/5 patterns", + "threshold": "\u226570% of language-specific patterns", + "evidence": [ + ".gitignore found (120 bytes)", + "Pattern coverage: 0/5 (0%)", + "Missing 5 recommended patterns" + ], + "remediation": { + "summary": "Add missing language-specific ignore patterns", + "steps": [ + "Review GitHub's gitignore templates for your language", + "Add the 5 missing patterns", + "Ensure editor/IDE patterns are included" + ], + "tools": [], + "commands": [], + "examples": [ + "# Missing patterns:\n.vscode/\n*.swp\n.idea/\n.DS_Store\n*.swo" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates Collection", + "url": "https://github.com/github/gitignore", + "relevance": "Comprehensive collection of language-specific gitignore patterns" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100, + "measured_value": "make dev-destroy", + "threshold": "single command", + "evidence": [ + "Setup command found in README: 'make dev-destroy'", + "Setup automation found: Makefile", + "Setup instructions in prominent location" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "No source files found to assess" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/0 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 67.0, + "measured_value": "69 lines, 8 headings, 2 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 69 lines (excellent)", + "Heading density: 11.6 per 100 lines (target: 3-5)", + "Only 2 bullet points (prefer bullets over prose)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML', 'Markdown']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML', 'Markdown']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "status": "fail", + "score": 70, + "measured_value": "basic config", + "threshold": "CI with best practices", + "evidence": [ + "CI config found: .gitlab-ci.yml", + "Descriptive job/step names found", + "No caching detected", + "No parallelization detected", + "Config includes comments" + ], + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Naming check not implemented for ['YAML', 'Markdown']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML', 'Markdown']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.0, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/aipcc-infrastructure/2026-03-24T17-58-24-assessment.json b/submissions/redhat/aipcc-infrastructure/2026-03-24T17-58-24-assessment.json new file mode 100644 index 00000000..94dd9760 --- /dev/null +++ b/submissions/redhat/aipcc-infrastructure/2026-03-24T17-58-24-assessment.json @@ -0,0 +1,713 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:24.017401", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@386d840e6a97", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/ci-cd/aipcc-infrastructure.git", + "branch": "main", + "commit_hash": "e3ea2238df62758ef86058c4c78285c64d68b30e", + "languages": {}, + "total_files": 45, + "total_lines": 1428 + }, + "timestamp": "2026-03-24T17:58:24.017401", + "overall_score": 27.6, + "certification_level": "Needs Improvement", + "attributes_assessed": 11, + "attributes_skipped": 7, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present", + "evidence": [ + "CLAUDE.md not found in repository root", + "AGENTS.md not found (alternative)" + ], + "remediation": { + "summary": "Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants", + "steps": [ + "Choose one of three approaches:", + " Option 1: Create standalone CLAUDE.md (>50 bytes) with project context", + " Option 2: Create AGENTS.md and symlink CLAUDE.md to it (cross-tool compatibility)", + " Option 3: Create AGENTS.md and reference it with @AGENTS.md in minimal CLAUDE.md", + "Add project overview and purpose", + "Document key architectural patterns", + "Specify coding standards and conventions", + "Include build/test/deployment commands", + "Add any project-specific context that helps AI assistants" + ], + "tools": [], + "commands": [ + "# Option 1: Standalone CLAUDE.md", + "touch CLAUDE.md", + "# Add content describing your project", + "", + "# Option 2: Symlink CLAUDE.md to AGENTS.md", + "touch AGENTS.md", + "# Add content to AGENTS.md", + "ln -s AGENTS.md CLAUDE.md", + "", + "# Option 3: @ reference in CLAUDE.md", + "echo '@AGENTS.md' > CLAUDE.md", + "touch AGENTS.md", + "# Add content to AGENTS.md" + ], + "examples": [ + "# Standalone CLAUDE.md (Option 1)\n\n## Overview\nBrief description of what this project does.\n\n## Architecture\nKey patterns and structure.\n\n## Development\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## Coding Standards\n- Use TypeScript strict mode\n- Follow ESLint configuration\n- Write tests for new features\n", + "# CLAUDE.md with @ reference (Option 3)\n@AGENTS.md\n", + "# AGENTS.md (shared by multiple tools)\n\n## Project Overview\nThis project implements a REST API for user management.\n\n## Architecture\n- Layered architecture: controllers, services, repositories\n- PostgreSQL database with SQLAlchemy ORM\n- FastAPI web framework\n\n## Development Workflow\n```bash\n# Setup\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\n# Run tests\npytest\n\n# Start server\nuvicorn app.main:app --reload\n```\n\n## Code Conventions\n- Use type hints for all functions\n- Follow PEP 8 style guide\n- Write docstrings for public APIs\n- Maintain >80% test coverage\n" + ], + "citations": [ + { + "source": "Anthropic", + "title": "Claude Code Documentation", + "url": "https://docs.anthropic.com/claude-code", + "relevance": "Official guidance on CLAUDE.md configuration" + }, + { + "source": "agents.md", + "title": "AGENTS.md Specification", + "url": "https://agents.md/", + "relevance": "Emerging standard for cross-tool AI assistant configuration" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "fail", + "score": 66.66666666666666, + "measured_value": "2/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 2/3 essential sections", + "Installation: \u2713", + "Usage: \u2713", + "Development: \u2717" + ], + "remediation": { + "summary": "Create or enhance README.md with essential sections", + "steps": [ + "Add project overview and description", + "Include installation/setup instructions", + "Document basic usage with examples", + "Add development/contributing guidelines", + "Include build and test commands" + ], + "tools": [], + "commands": [], + "examples": [ + "# Project Name\n\n## Overview\nWhat this project does and why it exists.\n\n## Installation\n```bash\npip install -e .\n```\n\n## Usage\n```bash\nmyproject --help\n```\n\n## Development\n```bash\n# Run tests\npytest\n\n# Format code\nblack .\n```\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "About READMEs", + "url": "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes", + "relevance": "Best practices for README structure" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to []" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 0/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py", + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py", + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/5 patterns", + "threshold": "\u226570% of language-specific patterns", + "evidence": [ + ".gitignore found (913 bytes)", + "Pattern coverage: 0/5 (0%)", + "Missing 5 recommended patterns" + ], + "remediation": { + "summary": "Add missing language-specific ignore patterns", + "steps": [ + "Review GitHub's gitignore templates for your language", + "Add the 5 missing patterns", + "Ensure editor/IDE patterns are included" + ], + "tools": [], + "commands": [], + "examples": [ + "# Missing patterns:\n.idea/\n.vscode/\n*.swp\n.DS_Store\n*.swo" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates Collection", + "url": "https://github.com/github/gitignore", + "relevance": "Comprehensive collection of language-specific gitignore patterns" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100, + "measured_value": "make tf", + "threshold": "single command", + "evidence": [ + "Setup command found in README: 'make tf'", + "Setup automation found: Makefile", + "Setup instructions in prominent location" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "No source files found to assess" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/16 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 67.0, + "measured_value": "141 lines, 17 headings, 0 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 141 lines (excellent)", + "Heading density: 12.1 per 100 lines (target: 3-5)", + "Only 0 bullet points (prefer bullets over prose)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to []" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to []" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "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": { + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to []" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to []" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.3, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/aipcc-product-management-configs/2026-03-24T17-58-25-assessment.json b/submissions/redhat/aipcc-product-management-configs/2026-03-24T17-58-25-assessment.json new file mode 100644 index 00000000..ad20cde4 --- /dev/null +++ b/submissions/redhat/aipcc-product-management-configs/2026-03-24T17-58-25-assessment.json @@ -0,0 +1,703 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:25.131832", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@c46fd418ce43", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/ci-cd/aipcc-product-management-configs.git", + "branch": "main", + "commit_hash": "7eb336d21c5eaf088c6e334777430f8baab1098d", + "languages": { + "Markdown": 12, + "YAML": 104 + }, + "total_files": 118, + "total_lines": 8047 + }, + "timestamp": "2026-03-24T17:58:25.131832", + "overall_score": 49.3, + "certification_level": "Bronze", + "attributes_assessed": 11, + "attributes_skipped": 7, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "present", + "threshold": "present", + "evidence": [ + "CLAUDE.md found at /repo/CLAUDE.md" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "fail", + "score": 66.66666666666666, + "measured_value": "2/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 2/3 essential sections", + "Installation: \u2717", + "Usage: \u2713", + "Development: \u2713" + ], + "remediation": { + "summary": "Create or enhance README.md with essential sections", + "steps": [ + "Add project overview and description", + "Include installation/setup instructions", + "Document basic usage with examples", + "Add development/contributing guidelines", + "Include build and test commands" + ], + "tools": [], + "commands": [], + "examples": [ + "# Project Name\n\n## Overview\nWhat this project does and why it exists.\n\n## Installation\n```bash\npip install -e .\n```\n\n## Usage\n```bash\nmyproject --help\n```\n\n## Development\n```bash\n# Run tests\npytest\n\n# Format code\nblack .\n```\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "About READMEs", + "url": "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes", + "relevance": "Best practices for README structure" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown', 'YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 50.0, + "measured_value": "1/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 1/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2713" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present with language patterns", + "evidence": [ + ".gitignore not found" + ], + "remediation": { + "summary": "Create .gitignore file with language-specific patterns", + "steps": [ + "Create .gitignore file", + "Add language-specific patterns from GitHub templates", + "Include editor/IDE ignore patterns" + ], + "tools": [], + "commands": [ + "touch .gitignore" + ], + "examples": [ + "# Python .gitignore example\n__pycache__/\n*.py[cod]\n.venv/\n.env\n.pytest_cache/", + "# JavaScript .gitignore example\nnode_modules/\ndist/\nbuild/\n*.log\n.npm/" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates", + "url": "https://github.com/github/gitignore", + "relevance": "Community-maintained collection of .gitignore templates for various languages and frameworks" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0, + "measured_value": "multi-step setup", + "threshold": "single command", + "evidence": [ + "No clear setup command found in README", + "No Makefile or setup script found", + "Setup instructions not in first 3 sections" + ], + "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\n\n## Quick Start\n\n```bash\nmake setup # One command to set up development environment\nmake test # Run tests to verify setup\n```\n" + ], + "citations": [ + { + "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" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "No source files found to assess" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/0 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 67.0, + "measured_value": "144 lines, 22 headings, 17 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 144 lines (excellent)", + "Heading density: 15.3 per 100 lines (target: 3-5)", + "17 bullet points, 2 code blocks (concise formatting)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown', 'YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown', 'YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "status": "fail", + "score": 60, + "measured_value": "basic config", + "threshold": "CI with best practices", + "evidence": [ + "CI config found: .gitlab-ci.yml", + "Generic job names (consider more descriptive names)", + "No caching detected", + "No parallelization detected", + "Config includes comments" + ], + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Naming check not implemented for ['Markdown', 'YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown', 'YAML']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.1, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/aipcc-product-management/2026-03-24T17-58-26-assessment.json b/submissions/redhat/aipcc-product-management/2026-03-24T17-58-26-assessment.json new file mode 100644 index 00000000..53d814f1 --- /dev/null +++ b/submissions/redhat/aipcc-product-management/2026-03-24T17-58-26-assessment.json @@ -0,0 +1,668 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:26.058764", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@729a3c51fb68", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/ci-cd/aipcc-product-management.git", + "branch": "main", + "commit_hash": "33a8067e0d2b0c084698b50d372cf8f829b12432", + "languages": { + "YAML": 52, + "Python": 3 + }, + "total_files": 76, + "total_lines": 5494 + }, + "timestamp": "2026-03-24T17:58:26.058764", + "overall_score": 72.2, + "certification_level": "Silver", + "attributes_assessed": 17, + "attributes_skipped": 1, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "present", + "threshold": "present", + "evidence": [ + "CLAUDE.md found at /repo/CLAUDE.md" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "3/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 3/3 essential sections", + "Installation: \u2713", + "Usage: \u2713", + "Development: \u2713" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "fail", + "score": 18.867924528301888, + "measured_value": "15.1%", + "threshold": "\u226580%", + "evidence": [ + "Typed functions: 8/53", + "Coverage: 15.1%" + ], + "remediation": { + "summary": "Add type annotations to function signatures", + "steps": [ + "For Python: Add type hints to function parameters and return types", + "For TypeScript: Enable strict mode in tsconfig.json", + "Use mypy or pyright for Python type checking", + "Use tsc --strict for TypeScript", + "Add type annotations gradually to existing code" + ], + "tools": [ + "mypy", + "pyright", + "typescript" + ], + "commands": [ + "# Python", + "pip install mypy", + "mypy --strict src/", + "", + "# TypeScript", + "npm install --save-dev typescript", + "echo '{\"compilerOptions\": {\"strict\": true}}' > tsconfig.json" + ], + "examples": [ + "# Python - Before\ndef calculate(x, y):\n return x + y\n\n# Python - After\ndef calculate(x: float, y: float) -> float:\n return x + y\n", + "// TypeScript - tsconfig.json\n{\n \"compilerOptions\": {\n \"strict\": true,\n \"noImplicitAny\": true,\n \"strictNullChecks\": true\n }\n}\n" + ], + "citations": [ + { + "source": "Python.org", + "title": "Type Hints", + "url": "https://docs.python.org/3/library/typing.html", + "relevance": "Official Python type hints documentation" + }, + { + "source": "TypeScript", + "title": "TypeScript Handbook", + "url": "https://www.typescriptlang.org/docs/handbook/2/everyday-types.html", + "relevance": "TypeScript type system guide" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 50.0, + "measured_value": "1/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 1/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2713" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "uv.lock, requirements.txt", + "threshold": "lock file with pinned versions, < 6 months old", + "evidence": [ + "Found lock file(s): uv.lock" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "pass", + "score": 83.33333333333334, + "measured_value": "10/12 patterns", + "threshold": "\u226570% of language-specific patterns", + "evidence": [ + ".gitignore found (6743 bytes)", + "Pattern coverage: 10/12 (83%)", + "Missing 2 recommended patterns" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100, + "measured_value": "uv sync", + "threshold": "single command", + "evidence": [ + "Setup command found in README: 'uv sync'", + "Setup automation found: Makefile, pyproject.toml", + "Setup instructions in prominent location" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0, + "measured_value": "1 huge, 1 large out of 3", + "threshold": "<5% files >500 lines, 0 files >1000 lines", + "evidence": [ + "Found 1 files >1000 lines (33.3% of 3 files)", + "Largest: onboard-product.py (1420 lines)" + ], + "remediation": { + "summary": "Refactor large files into smaller, focused modules", + "steps": [ + "Identify files >1000 lines", + "Split into logical submodules", + "Extract classes/functions into separate files", + "Maintain single responsibility principle" + ], + "tools": [ + "refactoring tools", + "linters" + ], + "commands": [], + "examples": [ + "# Split large file:\n# models.py (1500 lines) \u2192 models/user.py, models/product.py, models/order.py" + ], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 80.0, + "measured_value": "organization:100, cohesion:33, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 2/3 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 58.0, + "measured_value": "560 lines, 66 headings, 86 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 560 lines (acceptable)", + "Heading density: 11.8 per 100 lines (target: 3-5)", + "3 paragraphs exceed 10 lines (walls of text)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "92.3%", + "threshold": "\u226580%", + "evidence": [ + "Documented items: 48/52", + "Coverage: 92.3%", + "Good docstring coverage" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "5.4", + "threshold": "<10.0", + "evidence": [ + "Average cyclomatic complexity: 5.4" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "status": "fail", + "score": 70, + "measured_value": "basic config", + "threshold": "CI with best practices", + "evidence": [ + "CI config found: .gitlab-ci.yml", + "Generic job names (consider more descriptive names)", + "No caching detected", + "Parallel job execution detected", + "Config includes comments" + ], + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "pass", + "score": 100.0, + "measured_value": "functions:100%, classes:100%", + "threshold": "\u226575% compliance", + "evidence": [ + "Functions: 45/45 follow snake_case (100.0%)", + "Classes: 4/4 follow PascalCase (100.0%)", + "No generic names (temp, data, obj) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "pass", + "score": 80.0, + "measured_value": "pylint, ruff", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "Linters configured: pylint, ruff", + "Coverage: 40/50 points (80%)" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "pass", + "score": 40, + "measured_value": "40 points", + "threshold": "\u226570 points (Dockerfile + compose + .dockerignore)", + "evidence": [ + "\u2713 Containerfile present (Podman)", + "\u2139\ufe0f Single-stage build (consider multi-stage for smaller images)", + "\u2139\ufe0f No .dockerignore file (consider adding to reduce image size)" + ], + "remediation": { + "summary": "Improve container configuration", + "steps": [ + "Add docker-compose.yml for multi-service development", + "Create .dockerignore to exclude build artifacts and secrets", + "Consider multi-stage builds to reduce image size" + ], + "tools": [ + "docker", + "podman", + "docker-compose" + ], + "commands": [ + "docker build -t myapp .", + "docker-compose up -d" + ], + "examples": [ + "# .dockerignore example\n.git\n.venv\n__pycache__\n*.pyc\n.env\nnode_modules", + "# Multi-stage Dockerfile example\nFROM node:18 AS builder\nWORKDIR /app\nCOPY . .\nRUN npm ci && npm run build\n\nFROM node:18-alpine\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]" + ], + "citations": [ + { + "source": "Docker", + "title": "Dockerfile Best Practices", + "url": "https://docs.docker.com/develop/develop-images/dockerfile_best-practices/", + "relevance": "Official Docker guide for writing efficient and secure Dockerfiles" + } + ] + }, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.2, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/bootc-test/2026-03-24T17-58-26-assessment.json b/submissions/redhat/bootc-test/2026-03-24T17-58-26-assessment.json new file mode 100644 index 00000000..2fe7f518 --- /dev/null +++ b/submissions/redhat/bootc-test/2026-03-24T17-58-26-assessment.json @@ -0,0 +1,735 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:26.180750", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@9ae8f872e26a", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/containers/bootc-test.git", + "branch": "main", + "commit_hash": "76a2c4cf6ff05d21786c62b65ba1261b209168ef", + "languages": { + "YAML": 4 + }, + "total_files": 10, + "total_lines": 435 + }, + "timestamp": "2026-03-24T17:58:26.180750", + "overall_score": 26.7, + "certification_level": "Needs Improvement", + "attributes_assessed": 11, + "attributes_skipped": 7, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present", + "evidence": [ + "CLAUDE.md not found in repository root", + "AGENTS.md not found (alternative)" + ], + "remediation": { + "summary": "Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants", + "steps": [ + "Choose one of three approaches:", + " Option 1: Create standalone CLAUDE.md (>50 bytes) with project context", + " Option 2: Create AGENTS.md and symlink CLAUDE.md to it (cross-tool compatibility)", + " Option 3: Create AGENTS.md and reference it with @AGENTS.md in minimal CLAUDE.md", + "Add project overview and purpose", + "Document key architectural patterns", + "Specify coding standards and conventions", + "Include build/test/deployment commands", + "Add any project-specific context that helps AI assistants" + ], + "tools": [], + "commands": [ + "# Option 1: Standalone CLAUDE.md", + "touch CLAUDE.md", + "# Add content describing your project", + "", + "# Option 2: Symlink CLAUDE.md to AGENTS.md", + "touch AGENTS.md", + "# Add content to AGENTS.md", + "ln -s AGENTS.md CLAUDE.md", + "", + "# Option 3: @ reference in CLAUDE.md", + "echo '@AGENTS.md' > CLAUDE.md", + "touch AGENTS.md", + "# Add content to AGENTS.md" + ], + "examples": [ + "# Standalone CLAUDE.md (Option 1)\n\n## Overview\nBrief description of what this project does.\n\n## Architecture\nKey patterns and structure.\n\n## Development\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## Coding Standards\n- Use TypeScript strict mode\n- Follow ESLint configuration\n- Write tests for new features\n", + "# CLAUDE.md with @ reference (Option 3)\n@AGENTS.md\n", + "# AGENTS.md (shared by multiple tools)\n\n## Project Overview\nThis project implements a REST API for user management.\n\n## Architecture\n- Layered architecture: controllers, services, repositories\n- PostgreSQL database with SQLAlchemy ORM\n- FastAPI web framework\n\n## Development Workflow\n```bash\n# Setup\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\n# Run tests\npytest\n\n# Start server\nuvicorn app.main:app --reload\n```\n\n## Code Conventions\n- Use type hints for all functions\n- Follow PEP 8 style guide\n- Write docstrings for public APIs\n- Maintain >80% test coverage\n" + ], + "citations": [ + { + "source": "Anthropic", + "title": "Claude Code Documentation", + "url": "https://docs.anthropic.com/claude-code", + "relevance": "Official guidance on CLAUDE.md configuration" + }, + { + "source": "agents.md", + "title": "AGENTS.md Specification", + "url": "https://agents.md/", + "relevance": "Emerging standard for cross-tool AI assistant configuration" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "3/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 3/3 essential sections", + "Installation: \u2713", + "Usage: \u2713", + "Development: \u2713" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 0/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py", + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py", + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "fail", + "score": 0, + "measured_value": "No security scanning tools configured", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "No security scanning tools detected" + ], + "remediation": { + "summary": "Configure security scanning for dependencies and code", + "steps": [ + "Enable Dependabot in GitHub repository settings", + "Add .github/dependabot.yml configuration file", + "Or configure Renovate: add renovate.json to repository root", + "Set up CodeQL scanning for SAST", + "Add secret detection to pre-commit hooks", + "Configure language-specific security scanners" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "Bandit", + "Semgrep" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install pre-commit detect-secrets", + "pre-commit install" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly", + "# renovate.json\n{\n \"extends\": [\"config:base\"],\n \"schedule\": \"after 10pm every weekday\"\n}", + "# .pre-commit-config.yaml\nrepos:\n - repo: https://github.com/Yelp/detect-secrets\n rev: v1.4.0\n hooks:\n - id: detect-secrets" + ], + "citations": [ + { + "source": "OWASP", + "title": "OWASP Top 10", + "url": "https://owasp.org/www-project-top-ten/", + "relevance": "Industry-standard list of critical web application security risks" + }, + { + "source": "GitHub", + "title": "Security Best Practices", + "url": "https://docs.github.com/en/code-security", + "relevance": "Official GitHub security features and best practices documentation" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present with language patterns", + "evidence": [ + ".gitignore not found" + ], + "remediation": { + "summary": "Create .gitignore file with language-specific patterns", + "steps": [ + "Create .gitignore file", + "Add language-specific patterns from GitHub templates", + "Include editor/IDE ignore patterns" + ], + "tools": [], + "commands": [ + "touch .gitignore" + ], + "examples": [ + "# Python .gitignore example\n__pycache__/\n*.py[cod]\n.venv/\n.env\n.pytest_cache/", + "# JavaScript .gitignore example\nnode_modules/\ndist/\nbuild/\n*.log\n.npm/" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates", + "url": "https://github.com/github/gitignore", + "relevance": "Community-maintained collection of .gitignore templates for various languages and frameworks" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "fail", + "score": 30, + "measured_value": "multi-step setup", + "threshold": "single command", + "evidence": [ + "No clear setup command found in README", + "No Makefile or setup script found", + "Setup instructions in prominent location" + ], + "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\n\n## Quick Start\n\n```bash\nmake setup # One command to set up development environment\nmake test # Run tests to verify setup\n```\n" + ], + "citations": [ + { + "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" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "No source files found to assess" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/0 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 67.0, + "measured_value": "93 lines, 20 headings, 13 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 93 lines (excellent)", + "Heading density: 21.5 per 100 lines (target: 3-5)", + "13 bullet points, 1 code blocks (concise formatting)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "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": { + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Naming check not implemented for ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.0, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/bootc/2026-03-24T17-58-24-assessment.json b/submissions/redhat/bootc/2026-03-24T17-58-24-assessment.json new file mode 100644 index 00000000..baad0a71 --- /dev/null +++ b/submissions/redhat/bootc/2026-03-24T17-58-24-assessment.json @@ -0,0 +1,700 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:24.843049", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@1f7862a33abe", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/containers/bootc.git", + "branch": "main", + "commit_hash": "f6a68653f966a36f730106f46becea041ea60bb4", + "languages": { + "YAML": 41, + "Shell": 4, + "TOML": 4 + }, + "total_files": 83, + "total_lines": 4088 + }, + "timestamp": "2026-03-24T17:58:24.843049", + "overall_score": 34.1, + "certification_level": "Needs Improvement", + "attributes_assessed": 11, + "attributes_skipped": 7, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present", + "evidence": [ + "CLAUDE.md not found in repository root", + "AGENTS.md not found (alternative)" + ], + "remediation": { + "summary": "Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants", + "steps": [ + "Choose one of three approaches:", + " Option 1: Create standalone CLAUDE.md (>50 bytes) with project context", + " Option 2: Create AGENTS.md and symlink CLAUDE.md to it (cross-tool compatibility)", + " Option 3: Create AGENTS.md and reference it with @AGENTS.md in minimal CLAUDE.md", + "Add project overview and purpose", + "Document key architectural patterns", + "Specify coding standards and conventions", + "Include build/test/deployment commands", + "Add any project-specific context that helps AI assistants" + ], + "tools": [], + "commands": [ + "# Option 1: Standalone CLAUDE.md", + "touch CLAUDE.md", + "# Add content describing your project", + "", + "# Option 2: Symlink CLAUDE.md to AGENTS.md", + "touch AGENTS.md", + "# Add content to AGENTS.md", + "ln -s AGENTS.md CLAUDE.md", + "", + "# Option 3: @ reference in CLAUDE.md", + "echo '@AGENTS.md' > CLAUDE.md", + "touch AGENTS.md", + "# Add content to AGENTS.md" + ], + "examples": [ + "# Standalone CLAUDE.md (Option 1)\n\n## Overview\nBrief description of what this project does.\n\n## Architecture\nKey patterns and structure.\n\n## Development\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## Coding Standards\n- Use TypeScript strict mode\n- Follow ESLint configuration\n- Write tests for new features\n", + "# CLAUDE.md with @ reference (Option 3)\n@AGENTS.md\n", + "# AGENTS.md (shared by multiple tools)\n\n## Project Overview\nThis project implements a REST API for user management.\n\n## Architecture\n- Layered architecture: controllers, services, repositories\n- PostgreSQL database with SQLAlchemy ORM\n- FastAPI web framework\n\n## Development Workflow\n```bash\n# Setup\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\n# Run tests\npytest\n\n# Start server\nuvicorn app.main:app --reload\n```\n\n## Code Conventions\n- Use type hints for all functions\n- Follow PEP 8 style guide\n- Write docstrings for public APIs\n- Maintain >80% test coverage\n" + ], + "citations": [ + { + "source": "Anthropic", + "title": "Claude Code Documentation", + "url": "https://docs.anthropic.com/claude-code", + "relevance": "Official guidance on CLAUDE.md configuration" + }, + { + "source": "agents.md", + "title": "AGENTS.md Specification", + "url": "https://agents.md/", + "relevance": "Emerging standard for cross-tool AI assistant configuration" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "3/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 3/3 essential sections", + "Installation: \u2713", + "Usage: \u2713", + "Development: \u2713" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML', 'Shell', 'TOML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 0/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py", + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py", + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 40.0, + "measured_value": "2/5 patterns", + "threshold": "\u226570% of language-specific patterns", + "evidence": [ + ".gitignore found (29 bytes)", + "Pattern coverage: 2/5 (40%)", + "Missing 3 recommended patterns" + ], + "remediation": { + "summary": "Add missing language-specific ignore patterns", + "steps": [ + "Review GitHub's gitignore templates for your language", + "Add the 3 missing patterns", + "Ensure editor/IDE patterns are included" + ], + "tools": [], + "commands": [], + "examples": [ + "# Missing patterns:\n*.swp\n.vscode/\n*.swo" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates Collection", + "url": "https://github.com/github/gitignore", + "relevance": "Comprehensive collection of language-specific gitignore patterns" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "fail", + "score": 30, + "measured_value": "multi-step setup", + "threshold": "single command", + "evidence": [ + "No clear setup command found in README", + "No Makefile or setup script found", + "Setup instructions in prominent location" + ], + "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\n\n## Quick Start\n\n```bash\nmake setup # One command to set up development environment\nmake test # Run tests to verify setup\n```\n" + ], + "citations": [ + { + "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" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "No source files found to assess" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/0 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "pass", + "score": 84.0, + "measured_value": "293 lines, 23 headings, 50 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 293 lines (excellent)", + "Heading density: 7.8 per 100 lines (target: 3-5)", + "50 bullet points, 10 code blocks (concise formatting)" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML', 'Shell', 'TOML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML', 'Shell', 'TOML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "status": "fail", + "score": 60, + "measured_value": "basic config", + "threshold": "CI with best practices", + "evidence": [ + "CI config found: .gitlab-ci.yml", + "Generic job names (consider more descriptive names)", + "No caching detected", + "No parallelization detected", + "Config includes comments" + ], + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Naming check not implemented for ['YAML', 'Shell', 'TOML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML', 'Shell', 'TOML']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.0, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/central-linter/2026-03-24T17-58-23-assessment.json b/submissions/redhat/central-linter/2026-03-24T17-58-23-assessment.json new file mode 100644 index 00000000..c3051ba5 --- /dev/null +++ b/submissions/redhat/central-linter/2026-03-24T17-58-23-assessment.json @@ -0,0 +1,790 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:23.529765", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@9b7b6461e18a", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/ci-cd/central-linter.git", + "branch": "main", + "commit_hash": "e52be3175f8f4eb0e350c1a01b801d019b3c7f1d", + "languages": { + "YAML": 4, + "Python": 4 + }, + "total_files": 19, + "total_lines": 3360 + }, + "timestamp": "2026-03-24T17:58:23.529765", + "overall_score": 45.9, + "certification_level": "Bronze", + "attributes_assessed": 17, + "attributes_skipped": 1, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present", + "evidence": [ + "CLAUDE.md not found in repository root", + "AGENTS.md not found (alternative)" + ], + "remediation": { + "summary": "Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants", + "steps": [ + "Choose one of three approaches:", + " Option 1: Create standalone CLAUDE.md (>50 bytes) with project context", + " Option 2: Create AGENTS.md and symlink CLAUDE.md to it (cross-tool compatibility)", + " Option 3: Create AGENTS.md and reference it with @AGENTS.md in minimal CLAUDE.md", + "Add project overview and purpose", + "Document key architectural patterns", + "Specify coding standards and conventions", + "Include build/test/deployment commands", + "Add any project-specific context that helps AI assistants" + ], + "tools": [], + "commands": [ + "# Option 1: Standalone CLAUDE.md", + "touch CLAUDE.md", + "# Add content describing your project", + "", + "# Option 2: Symlink CLAUDE.md to AGENTS.md", + "touch AGENTS.md", + "# Add content to AGENTS.md", + "ln -s AGENTS.md CLAUDE.md", + "", + "# Option 3: @ reference in CLAUDE.md", + "echo '@AGENTS.md' > CLAUDE.md", + "touch AGENTS.md", + "# Add content to AGENTS.md" + ], + "examples": [ + "# Standalone CLAUDE.md (Option 1)\n\n## Overview\nBrief description of what this project does.\n\n## Architecture\nKey patterns and structure.\n\n## Development\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## Coding Standards\n- Use TypeScript strict mode\n- Follow ESLint configuration\n- Write tests for new features\n", + "# CLAUDE.md with @ reference (Option 3)\n@AGENTS.md\n", + "# AGENTS.md (shared by multiple tools)\n\n## Project Overview\nThis project implements a REST API for user management.\n\n## Architecture\n- Layered architecture: controllers, services, repositories\n- PostgreSQL database with SQLAlchemy ORM\n- FastAPI web framework\n\n## Development Workflow\n```bash\n# Setup\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\n# Run tests\npytest\n\n# Start server\nuvicorn app.main:app --reload\n```\n\n## Code Conventions\n- Use type hints for all functions\n- Follow PEP 8 style guide\n- Write docstrings for public APIs\n- Maintain >80% test coverage\n" + ], + "citations": [ + { + "source": "Anthropic", + "title": "Claude Code Documentation", + "url": "https://docs.anthropic.com/claude-code", + "relevance": "Official guidance on CLAUDE.md configuration" + }, + { + "source": "agents.md", + "title": "AGENTS.md Specification", + "url": "https://agents.md/", + "relevance": "Emerging standard for cross-tool AI assistant configuration" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "3/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 3/3 essential sections", + "Installation: \u2713", + "Usage: \u2713", + "Development: \u2713" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "fail", + "score": 35.57692307692307, + "measured_value": "28.5%", + "threshold": "\u226580%", + "evidence": [ + "Typed functions: 37/130", + "Coverage: 28.5%" + ], + "remediation": { + "summary": "Add type annotations to function signatures", + "steps": [ + "For Python: Add type hints to function parameters and return types", + "For TypeScript: Enable strict mode in tsconfig.json", + "Use mypy or pyright for Python type checking", + "Use tsc --strict for TypeScript", + "Add type annotations gradually to existing code" + ], + "tools": [ + "mypy", + "pyright", + "typescript" + ], + "commands": [ + "# Python", + "pip install mypy", + "mypy --strict src/", + "", + "# TypeScript", + "npm install --save-dev typescript", + "echo '{\"compilerOptions\": {\"strict\": true}}' > tsconfig.json" + ], + "examples": [ + "# Python - Before\ndef calculate(x, y):\n return x + y\n\n# Python - After\ndef calculate(x: float, y: float) -> float:\n return x + y\n", + "// TypeScript - tsconfig.json\n{\n \"compilerOptions\": {\n \"strict\": true,\n \"noImplicitAny\": true,\n \"strictNullChecks\": true\n }\n}\n" + ], + "citations": [ + { + "source": "Python.org", + "title": "Type Hints", + "url": "https://docs.python.org/3/library/typing.html", + "relevance": "Official Python type hints documentation" + }, + { + "source": "TypeScript", + "title": "TypeScript Handbook", + "url": "https://www.typescriptlang.org/docs/handbook/2/everyday-types.html", + "relevance": "TypeScript type system guide" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 50.0, + "measured_value": "1/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 1/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2713" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present with language patterns", + "evidence": [ + ".gitignore not found" + ], + "remediation": { + "summary": "Create .gitignore file with language-specific patterns", + "steps": [ + "Create .gitignore file", + "Add language-specific patterns from GitHub templates", + "Include editor/IDE ignore patterns" + ], + "tools": [], + "commands": [ + "touch .gitignore" + ], + "examples": [ + "# Python .gitignore example\n__pycache__/\n*.py[cod]\n.venv/\n.env\n.pytest_cache/", + "# JavaScript .gitignore example\nnode_modules/\ndist/\nbuild/\n*.log\n.npm/" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates", + "url": "https://github.com/github/gitignore", + "relevance": "Community-maintained collection of .gitignore templates for various languages and frameworks" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100, + "measured_value": "pip install", + "threshold": "single command", + "evidence": [ + "Setup command found in README: 'pip install'", + "Setup automation found: Makefile", + "Setup instructions in prominent location" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0, + "measured_value": "2 huge, 0 large out of 4", + "threshold": "<5% files >500 lines, 0 files >1000 lines", + "evidence": [ + "Found 2 files >1000 lines (50.0% of 4 files)", + "Largest: scripts/mr_commit_linter.py (1079 lines)" + ], + "remediation": { + "summary": "Refactor large files into smaller, focused modules", + "steps": [ + "Identify files >1000 lines", + "Split into logical submodules", + "Extract classes/functions into separate files", + "Maintain single responsibility principle" + ], + "tools": [ + "refactoring tools", + "linters" + ], + "commands": [], + "examples": [ + "# Split large file:\n# models.py (1500 lines) \u2192 models/user.py, models/product.py, models/order.py" + ], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 85.0, + "measured_value": "organization:100, cohesion:50, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 2/4 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 40.0, + "measured_value": "905 lines, 96 headings, 41 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 905 lines (excessive)", + "Heading density: 10.6 per 100 lines (target: 3-5)", + "3 paragraphs exceed 10 lines (walls of text)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "98.7%", + "threshold": "\u226580%", + "evidence": [ + "Documented items: 148/150", + "Coverage: 98.7%", + "Good docstring coverage" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "2.9", + "threshold": "<10.0", + "evidence": [ + "Average cyclomatic complexity: 2.9" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "status": "fail", + "score": 70, + "measured_value": "basic config", + "threshold": "CI with best practices", + "evidence": [ + "CI config found: .gitlab-ci.yml", + "Descriptive job/step names found", + "No caching detected", + "No parallelization detected", + "Config includes comments" + ], + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "pass", + "score": 100.0, + "measured_value": "functions:100%, classes:100%", + "threshold": "\u226575% compliance", + "evidence": [ + "Functions: 130/130 follow snake_case (100.0%)", + "Classes: 16/16 follow PascalCase (100.0%)", + "No generic names (temp, data, obj) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 40.0, + "measured_value": "ruff", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "Linters configured: ruff", + "Coverage: 20/50 points (40%)" + ], + "remediation": { + "summary": "Configure 2 missing linter(s)", + "steps": [ + "Configure pylint for Python code smell detection", + "Configure markdownlint for documentation quality" + ], + "tools": [ + "pylint", + "markdownlint" + ], + "commands": [ + "pip install pylint && pylint --generate-rcfile > .pylintrc", + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "pass", + "score": 40, + "measured_value": "40 points", + "threshold": "\u226570 points (Dockerfile + compose + .dockerignore)", + "evidence": [ + "\u2713 Containerfile present (Podman)", + "\u2139\ufe0f Single-stage build (consider multi-stage for smaller images)", + "\u2139\ufe0f No .dockerignore file (consider adding to reduce image size)" + ], + "remediation": { + "summary": "Improve container configuration", + "steps": [ + "Add docker-compose.yml for multi-service development", + "Create .dockerignore to exclude build artifacts and secrets", + "Consider multi-stage builds to reduce image size" + ], + "tools": [ + "docker", + "podman", + "docker-compose" + ], + "commands": [ + "docker build -t myapp .", + "docker-compose up -d" + ], + "examples": [ + "# .dockerignore example\n.git\n.venv\n__pycache__\n*.pyc\n.env\nnode_modules", + "# Multi-stage Dockerfile example\nFROM node:18 AS builder\nWORKDIR /app\nCOPY . .\nRUN npm ci && npm run build\n\nFROM node:18-alpine\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]" + ], + "citations": [ + { + "source": "Docker", + "title": "Dockerfile Best Practices", + "url": "https://docs.docker.com/develop/develop-images/dockerfile_best-practices/", + "relevance": "Official Docker guide for writing efficient and secure Dockerfiles" + } + ] + }, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.1, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/dashboard/2026-03-24T17-58-23-assessment.json b/submissions/redhat/dashboard/2026-03-24T17-58-23-assessment.json new file mode 100644 index 00000000..9b365e43 --- /dev/null +++ b/submissions/redhat/dashboard/2026-03-24T17-58-23-assessment.json @@ -0,0 +1,670 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:23.812964", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@671d889987a3", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/ci-cd/dashboard.git", + "branch": "main", + "commit_hash": "929f74b5a65a279f29f2c3cd81f1bc3bedf73401", + "languages": { + "Markdown": 8, + "YAML": 37, + "Python": 123, + "JSON": 4, + "JavaScript": 87 + }, + "total_files": 287, + "total_lines": 72452 + }, + "timestamp": "2026-03-24T17:58:23.812964", + "overall_score": 58.5, + "certification_level": "Bronze", + "attributes_assessed": 16, + "attributes_skipped": 2, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "present", + "threshold": "present", + "evidence": [ + "CLAUDE.md found at /repo/CLAUDE.md" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "fail", + "score": 66.66666666666666, + "measured_value": "2/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 2/3 essential sections", + "Installation: \u2713", + "Usage: \u2717", + "Development: \u2713" + ], + "remediation": { + "summary": "Create or enhance README.md with essential sections", + "steps": [ + "Add project overview and description", + "Include installation/setup instructions", + "Document basic usage with examples", + "Add development/contributing guidelines", + "Include build and test commands" + ], + "tools": [], + "commands": [], + "examples": [ + "# Project Name\n\n## Overview\nWhat this project does and why it exists.\n\n## Installation\n```bash\npip install -e .\n```\n\n## Usage\n```bash\nmyproject --help\n```\n\n## Development\n```bash\n# Run tests\npytest\n\n# Format code\nblack .\n```\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "About READMEs", + "url": "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes", + "relevance": "Best practices for README structure" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "fail", + "score": 33.43270868824531, + "measured_value": "26.7%", + "threshold": "\u226580%", + "evidence": [ + "Typed functions: 157/587", + "Coverage: 26.7%" + ], + "remediation": { + "summary": "Add type annotations to function signatures", + "steps": [ + "For Python: Add type hints to function parameters and return types", + "For TypeScript: Enable strict mode in tsconfig.json", + "Use mypy or pyright for Python type checking", + "Use tsc --strict for TypeScript", + "Add type annotations gradually to existing code" + ], + "tools": [ + "mypy", + "pyright", + "typescript" + ], + "commands": [ + "# Python", + "pip install mypy", + "mypy --strict src/", + "", + "# TypeScript", + "npm install --save-dev typescript", + "echo '{\"compilerOptions\": {\"strict\": true}}' > tsconfig.json" + ], + "examples": [ + "# Python - Before\ndef calculate(x, y):\n return x + y\n\n# Python - After\ndef calculate(x: float, y: float) -> float:\n return x + y\n", + "// TypeScript - tsconfig.json\n{\n \"compilerOptions\": {\n \"strict\": true,\n \"noImplicitAny\": true,\n \"strictNullChecks\": true\n }\n}\n" + ], + "citations": [ + { + "source": "Python.org", + "title": "Type Hints", + "url": "https://docs.python.org/3/library/typing.html", + "relevance": "Official Python type hints documentation" + }, + { + "source": "TypeScript", + "title": "TypeScript Handbook", + "url": "https://www.typescriptlang.org/docs/handbook/2/everyday-types.html", + "relevance": "TypeScript type system guide" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 50.0, + "measured_value": "1/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 1/2 standard directories", + "source (heuristic): \u2713 (backend/) \u2014 verify", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "pass", + "score": 82.35294117647058, + "measured_value": "14/17 patterns", + "threshold": "\u226570% of language-specific patterns", + "evidence": [ + ".gitignore found (3697 bytes)", + "Pattern coverage: 14/17 (82%)", + "Missing 3 recommended patterns" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100, + "measured_value": "pre-commit install", + "threshold": "single command", + "evidence": [ + "Setup command found in README: 'pre-commit install'", + "Setup automation found: pyproject.toml", + "Setup instructions in prominent location" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "fail", + "score": 17.61904761904762, + "measured_value": "11 huge, 23 large out of 210", + "threshold": "<5% files >500 lines, 0 files >1000 lines", + "evidence": [ + "Found 11 files >1000 lines (5.2% of 210 files)", + "Largest: backend/api/tests/routers/test_artifacts.py (1915 lines)" + ], + "remediation": { + "summary": "Refactor large files into smaller, focused modules", + "steps": [ + "Identify files >1000 lines", + "Split into logical submodules", + "Extract classes/functions into separate files", + "Maintain single responsibility principle" + ], + "tools": [ + "refactoring tools", + "linters" + ], + "commands": [], + "examples": [ + "# Split large file:\n# models.py (1500 lines) \u2192 models/user.py, models/product.py, models/order.py" + ], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 94.8780487804878, + "measured_value": "organization:100, cohesion:83, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 21/123 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 61.0, + "measured_value": "335 lines, 41 headings, 15 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 335 lines (good)", + "Heading density: 12.2 per 100 lines (target: 3-5)", + "1 paragraphs exceed 10 lines (walls of text)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "pass", + "score": 82.75382475660639, + "measured_value": "66.2%", + "threshold": "\u226580%", + "evidence": [ + "Documented items: 476/719", + "Coverage: 66.2%", + "Moderate docstring coverage" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "4.6", + "threshold": "<10.0", + "evidence": [ + "Average cyclomatic complexity: 4.6" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "status": "pass", + "score": 80, + "measured_value": "configured with best practices", + "threshold": "CI with best practices", + "evidence": [ + "CI config found: .gitlab-ci.yml", + "Descriptive job/step names found", + "No caching detected", + "No parallelization detected", + "Config includes comments", + "Artifacts uploaded" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "pass", + "score": 100.0, + "measured_value": "functions:100%, classes:100%", + "threshold": "\u226575% compliance", + "evidence": [ + "Functions: 193/193 follow snake_case (100.0%)", + "Classes: 48/48 follow PascalCase (100.0%)", + "No generic names (temp, data, obj) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 57.14285714285714, + "measured_value": "pylint, ruff", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "Linters configured: pylint, ruff", + "Coverage: 40/70 points (57%)" + ], + "remediation": { + "summary": "Configure 2 missing linter(s)", + "steps": [ + "Configure ESLint for JavaScript/TypeScript", + "Configure markdownlint for documentation quality" + ], + "tools": [ + "ESLint", + "markdownlint" + ], + "commands": [ + "npm install --save-dev eslint && npx eslint --init", + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown', 'YAML', 'Python', 'JSON', 'JavaScript']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.9, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/disk-image-test/2026-03-24T17-58-27-assessment.json b/submissions/redhat/disk-image-test/2026-03-24T17-58-27-assessment.json new file mode 100644 index 00000000..9c6f1e73 --- /dev/null +++ b/submissions/redhat/disk-image-test/2026-03-24T17-58-27-assessment.json @@ -0,0 +1,735 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:27.575092", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@42fc82199dac", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/disk-images/disk-image-test.git", + "branch": "main", + "commit_hash": "41a8f73e78365ca7da1434b642dfbae20f39cfd2", + "languages": { + "YAML": 3 + }, + "total_files": 5, + "total_lines": 214 + }, + "timestamp": "2026-03-24T17:58:27.575092", + "overall_score": 26.7, + "certification_level": "Needs Improvement", + "attributes_assessed": 11, + "attributes_skipped": 7, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present", + "evidence": [ + "CLAUDE.md not found in repository root", + "AGENTS.md not found (alternative)" + ], + "remediation": { + "summary": "Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants", + "steps": [ + "Choose one of three approaches:", + " Option 1: Create standalone CLAUDE.md (>50 bytes) with project context", + " Option 2: Create AGENTS.md and symlink CLAUDE.md to it (cross-tool compatibility)", + " Option 3: Create AGENTS.md and reference it with @AGENTS.md in minimal CLAUDE.md", + "Add project overview and purpose", + "Document key architectural patterns", + "Specify coding standards and conventions", + "Include build/test/deployment commands", + "Add any project-specific context that helps AI assistants" + ], + "tools": [], + "commands": [ + "# Option 1: Standalone CLAUDE.md", + "touch CLAUDE.md", + "# Add content describing your project", + "", + "# Option 2: Symlink CLAUDE.md to AGENTS.md", + "touch AGENTS.md", + "# Add content to AGENTS.md", + "ln -s AGENTS.md CLAUDE.md", + "", + "# Option 3: @ reference in CLAUDE.md", + "echo '@AGENTS.md' > CLAUDE.md", + "touch AGENTS.md", + "# Add content to AGENTS.md" + ], + "examples": [ + "# Standalone CLAUDE.md (Option 1)\n\n## Overview\nBrief description of what this project does.\n\n## Architecture\nKey patterns and structure.\n\n## Development\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## Coding Standards\n- Use TypeScript strict mode\n- Follow ESLint configuration\n- Write tests for new features\n", + "# CLAUDE.md with @ reference (Option 3)\n@AGENTS.md\n", + "# AGENTS.md (shared by multiple tools)\n\n## Project Overview\nThis project implements a REST API for user management.\n\n## Architecture\n- Layered architecture: controllers, services, repositories\n- PostgreSQL database with SQLAlchemy ORM\n- FastAPI web framework\n\n## Development Workflow\n```bash\n# Setup\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\n# Run tests\npytest\n\n# Start server\nuvicorn app.main:app --reload\n```\n\n## Code Conventions\n- Use type hints for all functions\n- Follow PEP 8 style guide\n- Write docstrings for public APIs\n- Maintain >80% test coverage\n" + ], + "citations": [ + { + "source": "Anthropic", + "title": "Claude Code Documentation", + "url": "https://docs.anthropic.com/claude-code", + "relevance": "Official guidance on CLAUDE.md configuration" + }, + { + "source": "agents.md", + "title": "AGENTS.md Specification", + "url": "https://agents.md/", + "relevance": "Emerging standard for cross-tool AI assistant configuration" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "3/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 3/3 essential sections", + "Installation: \u2713", + "Usage: \u2713", + "Development: \u2713" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 0/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py", + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py", + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "fail", + "score": 0, + "measured_value": "No security scanning tools configured", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "No security scanning tools detected" + ], + "remediation": { + "summary": "Configure security scanning for dependencies and code", + "steps": [ + "Enable Dependabot in GitHub repository settings", + "Add .github/dependabot.yml configuration file", + "Or configure Renovate: add renovate.json to repository root", + "Set up CodeQL scanning for SAST", + "Add secret detection to pre-commit hooks", + "Configure language-specific security scanners" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "Bandit", + "Semgrep" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install pre-commit detect-secrets", + "pre-commit install" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly", + "# renovate.json\n{\n \"extends\": [\"config:base\"],\n \"schedule\": \"after 10pm every weekday\"\n}", + "# .pre-commit-config.yaml\nrepos:\n - repo: https://github.com/Yelp/detect-secrets\n rev: v1.4.0\n hooks:\n - id: detect-secrets" + ], + "citations": [ + { + "source": "OWASP", + "title": "OWASP Top 10", + "url": "https://owasp.org/www-project-top-ten/", + "relevance": "Industry-standard list of critical web application security risks" + }, + { + "source": "GitHub", + "title": "Security Best Practices", + "url": "https://docs.github.com/en/code-security", + "relevance": "Official GitHub security features and best practices documentation" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present with language patterns", + "evidence": [ + ".gitignore not found" + ], + "remediation": { + "summary": "Create .gitignore file with language-specific patterns", + "steps": [ + "Create .gitignore file", + "Add language-specific patterns from GitHub templates", + "Include editor/IDE ignore patterns" + ], + "tools": [], + "commands": [ + "touch .gitignore" + ], + "examples": [ + "# Python .gitignore example\n__pycache__/\n*.py[cod]\n.venv/\n.env\n.pytest_cache/", + "# JavaScript .gitignore example\nnode_modules/\ndist/\nbuild/\n*.log\n.npm/" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates", + "url": "https://github.com/github/gitignore", + "relevance": "Community-maintained collection of .gitignore templates for various languages and frameworks" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "fail", + "score": 30, + "measured_value": "multi-step setup", + "threshold": "single command", + "evidence": [ + "No clear setup command found in README", + "No Makefile or setup script found", + "Setup instructions in prominent location" + ], + "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\n\n## Quick Start\n\n```bash\nmake setup # One command to set up development environment\nmake test # Run tests to verify setup\n```\n" + ], + "citations": [ + { + "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" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "No source files found to assess" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/0 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 67.0, + "measured_value": "93 lines, 20 headings, 13 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 93 lines (excellent)", + "Heading density: 21.5 per 100 lines (target: 3-5)", + "13 bullet points, 1 code blocks (concise formatting)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "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": { + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Naming check not implemented for ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.0, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/docs/2026-03-24T17-58-26-assessment.json b/submissions/redhat/docs/2026-03-24T17-58-26-assessment.json new file mode 100644 index 00000000..51883f96 --- /dev/null +++ b/submissions/redhat/docs/2026-03-24T17-58-26-assessment.json @@ -0,0 +1,687 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:26.082061", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@21be433102ee", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/ci-cd/docs.git", + "branch": "main", + "commit_hash": "94ee7d1f7d51a4a49891ac4c2d8bac00f1de7df2", + "languages": { + "Markdown": 31 + }, + "total_files": 37, + "total_lines": 2010 + }, + "timestamp": "2026-03-24T17:58:26.082061", + "overall_score": 60.9, + "certification_level": "Silver", + "attributes_assessed": 11, + "attributes_skipped": 7, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "present", + "threshold": "present", + "evidence": [ + "CLAUDE.md found at /repo/CLAUDE.md" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "fail", + "score": 66.66666666666666, + "measured_value": "2/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 2/3 essential sections", + "Installation: \u2713", + "Usage: \u2717", + "Development: \u2713" + ], + "remediation": { + "summary": "Create or enhance README.md with essential sections", + "steps": [ + "Add project overview and description", + "Include installation/setup instructions", + "Document basic usage with examples", + "Add development/contributing guidelines", + "Include build and test commands" + ], + "tools": [], + "commands": [], + "examples": [ + "# Project Name\n\n## Overview\nWhat this project does and why it exists.\n\n## Installation\n```bash\npip install -e .\n```\n\n## Usage\n```bash\nmyproject --help\n```\n\n## Development\n```bash\n# Run tests\npytest\n\n# Format code\nblack .\n```\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "About READMEs", + "url": "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes", + "relevance": "Best practices for README structure" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 0/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py", + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py", + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "requirements.txt", + "threshold": "lock file with pinned versions, < 6 months old", + "evidence": [ + "Found requirements.txt: All 2 dependencies pinned" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 40.0, + "measured_value": "2/5 patterns", + "threshold": "\u226570% of language-specific patterns", + "evidence": [ + ".gitignore found (26 bytes)", + "Pattern coverage: 2/5 (40%)", + "Missing 3 recommended patterns" + ], + "remediation": { + "summary": "Add missing language-specific ignore patterns", + "steps": [ + "Review GitHub's gitignore templates for your language", + "Add the 3 missing patterns", + "Ensure editor/IDE patterns are included" + ], + "tools": [], + "commands": [], + "examples": [ + "# Missing patterns:\n.idea/\n.vscode/\n.DS_Store" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates Collection", + "url": "https://github.com/github/gitignore", + "relevance": "Comprehensive collection of language-specific gitignore patterns" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "fail", + "score": 30, + "measured_value": "multi-step setup", + "threshold": "single command", + "evidence": [ + "No clear setup command found in README", + "No Makefile or setup script found", + "Setup instructions in prominent location" + ], + "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\n\n## Quick Start\n\n```bash\nmake setup # One command to set up development environment\nmake test # Run tests to verify setup\n```\n" + ], + "citations": [ + { + "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" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "No source files found to assess" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/0 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 61.0, + "measured_value": "49 lines, 10 headings, 0 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 49 lines (excellent)", + "Heading density: 20.4 per 100 lines (target: 3-5)", + "Only 0 bullet points (prefer bullets over prose)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "status": "fail", + "score": 60, + "measured_value": "basic config", + "threshold": "CI with best practices", + "evidence": [ + "CI config found: .gitlab-ci.yml", + "Generic job names (consider more descriptive names)", + "No caching detected", + "No parallelization detected", + "Artifacts uploaded" + ], + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Naming check not implemented for ['Markdown']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.2, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/konflux-data/2026-03-24T17-58-24-assessment.json b/submissions/redhat/konflux-data/2026-03-24T17-58-24-assessment.json new file mode 100644 index 00000000..31570bd8 --- /dev/null +++ b/submissions/redhat/konflux-data/2026-03-24T17-58-24-assessment.json @@ -0,0 +1,754 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:24.139446", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@5ff6f7add1f4", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/konflux-data.git", + "branch": "main", + "commit_hash": "99be353a6c090137741d60a0a9ac3df1bd384ced", + "languages": { + "YAML": 130 + }, + "total_files": 134, + "total_lines": 7579 + }, + "timestamp": "2026-03-24T17:58:24.139446", + "overall_score": 15.3, + "certification_level": "Needs Improvement", + "attributes_assessed": 12, + "attributes_skipped": 6, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present", + "evidence": [ + "CLAUDE.md not found in repository root", + "AGENTS.md not found (alternative)" + ], + "remediation": { + "summary": "Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants", + "steps": [ + "Choose one of three approaches:", + " Option 1: Create standalone CLAUDE.md (>50 bytes) with project context", + " Option 2: Create AGENTS.md and symlink CLAUDE.md to it (cross-tool compatibility)", + " Option 3: Create AGENTS.md and reference it with @AGENTS.md in minimal CLAUDE.md", + "Add project overview and purpose", + "Document key architectural patterns", + "Specify coding standards and conventions", + "Include build/test/deployment commands", + "Add any project-specific context that helps AI assistants" + ], + "tools": [], + "commands": [ + "# Option 1: Standalone CLAUDE.md", + "touch CLAUDE.md", + "# Add content describing your project", + "", + "# Option 2: Symlink CLAUDE.md to AGENTS.md", + "touch AGENTS.md", + "# Add content to AGENTS.md", + "ln -s AGENTS.md CLAUDE.md", + "", + "# Option 3: @ reference in CLAUDE.md", + "echo '@AGENTS.md' > CLAUDE.md", + "touch AGENTS.md", + "# Add content to AGENTS.md" + ], + "examples": [ + "# Standalone CLAUDE.md (Option 1)\n\n## Overview\nBrief description of what this project does.\n\n## Architecture\nKey patterns and structure.\n\n## Development\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## Coding Standards\n- Use TypeScript strict mode\n- Follow ESLint configuration\n- Write tests for new features\n", + "# CLAUDE.md with @ reference (Option 3)\n@AGENTS.md\n", + "# AGENTS.md (shared by multiple tools)\n\n## Project Overview\nThis project implements a REST API for user management.\n\n## Architecture\n- Layered architecture: controllers, services, repositories\n- PostgreSQL database with SQLAlchemy ORM\n- FastAPI web framework\n\n## Development Workflow\n```bash\n# Setup\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\n# Run tests\npytest\n\n# Start server\nuvicorn app.main:app --reload\n```\n\n## Code Conventions\n- Use type hints for all functions\n- Follow PEP 8 style guide\n- Write docstrings for public APIs\n- Maintain >80% test coverage\n" + ], + "citations": [ + { + "source": "Anthropic", + "title": "Claude Code Documentation", + "url": "https://docs.anthropic.com/claude-code", + "relevance": "Official guidance on CLAUDE.md configuration" + }, + { + "source": "agents.md", + "title": "AGENTS.md Specification", + "url": "https://agents.md/", + "relevance": "Emerging standard for cross-tool AI assistant configuration" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 0/3 essential sections", + "Installation: \u2717", + "Usage: \u2717", + "Development: \u2717" + ], + "remediation": { + "summary": "Create or enhance README.md with essential sections", + "steps": [ + "Add project overview and description", + "Include installation/setup instructions", + "Document basic usage with examples", + "Add development/contributing guidelines", + "Include build and test commands" + ], + "tools": [], + "commands": [], + "examples": [ + "# Project Name\n\n## Overview\nWhat this project does and why it exists.\n\n## Installation\n```bash\npip install -e .\n```\n\n## Usage\n```bash\nmyproject --help\n```\n\n## Development\n```bash\n# Run tests\npytest\n\n# Format code\nblack .\n```\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "About READMEs", + "url": "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes", + "relevance": "Best practices for README structure" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 0/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py", + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py", + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present with language patterns", + "evidence": [ + ".gitignore not found" + ], + "remediation": { + "summary": "Create .gitignore file with language-specific patterns", + "steps": [ + "Create .gitignore file", + "Add language-specific patterns from GitHub templates", + "Include editor/IDE ignore patterns" + ], + "tools": [], + "commands": [ + "touch .gitignore" + ], + "examples": [ + "# Python .gitignore example\n__pycache__/\n*.py[cod]\n.venv/\n.env\n.pytest_cache/", + "# JavaScript .gitignore example\nnode_modules/\ndist/\nbuild/\n*.log\n.npm/" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates", + "url": "https://github.com/github/gitignore", + "relevance": "Community-maintained collection of .gitignore templates for various languages and frameworks" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0, + "measured_value": "multi-step setup", + "threshold": "single command", + "evidence": [ + "No clear setup command found in README", + "No Makefile or setup script found", + "Setup instructions not in first 3 sections" + ], + "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\n\n## Quick Start\n\n```bash\nmake setup # One command to set up development environment\nmake test # Run tests to verify setup\n```\n" + ], + "citations": [ + { + "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" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "0 huge, 0 large out of 1", + "threshold": "<5% files >500 lines, 0 files >1000 lines", + "evidence": [ + "All 1 source files are <500 lines" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/1 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 61.0, + "measured_value": "3 lines, 1 headings, 0 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 3 lines (excellent)", + "Heading density: 33.3 per 100 lines (target: 3-5)", + "Only 0 bullet points (prefer bullets over prose)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "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": { + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Naming check not implemented for ['YAML']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['YAML']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.1, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/renovate-config/2026-03-24T17-58-23-assessment.json b/submissions/redhat/renovate-config/2026-03-24T17-58-23-assessment.json new file mode 100644 index 00000000..1f548887 --- /dev/null +++ b/submissions/redhat/renovate-config/2026-03-24T17-58-23-assessment.json @@ -0,0 +1,756 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:23.905718", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@a6bb48cac2f6", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/renovate-config.git", + "branch": "main", + "commit_hash": "e508fca4e1f7335739d2e92cd3819e00a90b7a0c", + "languages": { + "JSON": 11 + }, + "total_files": 13, + "total_lines": 331 + }, + "timestamp": "2026-03-24T17:58:23.905718", + "overall_score": 24.1, + "certification_level": "Needs Improvement", + "attributes_assessed": 11, + "attributes_skipped": 7, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present", + "evidence": [ + "CLAUDE.md not found in repository root", + "AGENTS.md not found (alternative)" + ], + "remediation": { + "summary": "Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants", + "steps": [ + "Choose one of three approaches:", + " Option 1: Create standalone CLAUDE.md (>50 bytes) with project context", + " Option 2: Create AGENTS.md and symlink CLAUDE.md to it (cross-tool compatibility)", + " Option 3: Create AGENTS.md and reference it with @AGENTS.md in minimal CLAUDE.md", + "Add project overview and purpose", + "Document key architectural patterns", + "Specify coding standards and conventions", + "Include build/test/deployment commands", + "Add any project-specific context that helps AI assistants" + ], + "tools": [], + "commands": [ + "# Option 1: Standalone CLAUDE.md", + "touch CLAUDE.md", + "# Add content describing your project", + "", + "# Option 2: Symlink CLAUDE.md to AGENTS.md", + "touch AGENTS.md", + "# Add content to AGENTS.md", + "ln -s AGENTS.md CLAUDE.md", + "", + "# Option 3: @ reference in CLAUDE.md", + "echo '@AGENTS.md' > CLAUDE.md", + "touch AGENTS.md", + "# Add content to AGENTS.md" + ], + "examples": [ + "# Standalone CLAUDE.md (Option 1)\n\n## Overview\nBrief description of what this project does.\n\n## Architecture\nKey patterns and structure.\n\n## Development\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## Coding Standards\n- Use TypeScript strict mode\n- Follow ESLint configuration\n- Write tests for new features\n", + "# CLAUDE.md with @ reference (Option 3)\n@AGENTS.md\n", + "# AGENTS.md (shared by multiple tools)\n\n## Project Overview\nThis project implements a REST API for user management.\n\n## Architecture\n- Layered architecture: controllers, services, repositories\n- PostgreSQL database with SQLAlchemy ORM\n- FastAPI web framework\n\n## Development Workflow\n```bash\n# Setup\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\n# Run tests\npytest\n\n# Start server\nuvicorn app.main:app --reload\n```\n\n## Code Conventions\n- Use type hints for all functions\n- Follow PEP 8 style guide\n- Write docstrings for public APIs\n- Maintain >80% test coverage\n" + ], + "citations": [ + { + "source": "Anthropic", + "title": "Claude Code Documentation", + "url": "https://docs.anthropic.com/claude-code", + "relevance": "Official guidance on CLAUDE.md configuration" + }, + { + "source": "agents.md", + "title": "AGENTS.md Specification", + "url": "https://agents.md/", + "relevance": "Emerging standard for cross-tool AI assistant configuration" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "fail", + "score": 66.66666666666666, + "measured_value": "2/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 2/3 essential sections", + "Installation: \u2717", + "Usage: \u2713", + "Development: \u2713" + ], + "remediation": { + "summary": "Create or enhance README.md with essential sections", + "steps": [ + "Add project overview and description", + "Include installation/setup instructions", + "Document basic usage with examples", + "Add development/contributing guidelines", + "Include build and test commands" + ], + "tools": [], + "commands": [], + "examples": [ + "# Project Name\n\n## Overview\nWhat this project does and why it exists.\n\n## Installation\n```bash\npip install -e .\n```\n\n## Usage\n```bash\nmyproject --help\n```\n\n## Development\n```bash\n# Run tests\npytest\n\n# Format code\nblack .\n```\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "About READMEs", + "url": "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes", + "relevance": "Best practices for README structure" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['JSON']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 0/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py", + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py", + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "pass", + "score": 35, + "measured_value": "Security tools configured: Renovate", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Renovate configured for dependency updates", + " Meaningful Renovate configuration detected" + ], + "remediation": { + "summary": "Add more security scanning tools for comprehensive coverage", + "steps": [ + "Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)", + "Add CodeQL scanning workflow for SAST", + "Configure secret detection (detect-secrets, gitleaks)", + "Set up language-specific scanners (pip-audit, npm audit, Snyk)" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "pip-audit", + "npm audit" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install detect-secrets # Python secret detection", + "npm audit # JavaScript dependency audit" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly" + ], + "citations": [ + { + "source": "OWASP", + "title": "Dependency-Check Project", + "url": "https://owasp.org/www-project-dependency-check/", + "relevance": "Open-source tool for detecting known vulnerabilities in dependencies" + }, + { + "source": "GitHub", + "title": "Dependabot Documentation", + "url": "https://docs.github.com/en/code-security/dependabot", + "relevance": "Official guide for configuring automated dependency updates and security alerts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present with language patterns", + "evidence": [ + ".gitignore not found" + ], + "remediation": { + "summary": "Create .gitignore file with language-specific patterns", + "steps": [ + "Create .gitignore file", + "Add language-specific patterns from GitHub templates", + "Include editor/IDE ignore patterns" + ], + "tools": [], + "commands": [ + "touch .gitignore" + ], + "examples": [ + "# Python .gitignore example\n__pycache__/\n*.py[cod]\n.venv/\n.env\n.pytest_cache/", + "# JavaScript .gitignore example\nnode_modules/\ndist/\nbuild/\n*.log\n.npm/" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates", + "url": "https://github.com/github/gitignore", + "relevance": "Community-maintained collection of .gitignore templates for various languages and frameworks" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0, + "measured_value": "multi-step setup", + "threshold": "single command", + "evidence": [ + "No clear setup command found in README", + "No Makefile or setup script found", + "Setup instructions not in first 3 sections" + ], + "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\n\n## Quick Start\n\n```bash\nmake setup # One command to set up development environment\nmake test # Run tests to verify setup\n```\n" + ], + "citations": [ + { + "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" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "No source files found to assess" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/0 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 73.0, + "measured_value": "159 lines, 19 headings, 16 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 159 lines (excellent)", + "Heading density: 11.9 per 100 lines (target: 3-5)", + "16 bullet points, 8 code blocks (concise formatting)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['JSON']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['JSON']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "status": "fail", + "score": 50, + "measured_value": "basic config", + "threshold": "CI with best practices", + "evidence": [ + "CI config found: .gitlab-ci.yml", + "Generic job names (consider more descriptive names)", + "No caching detected", + "No parallelization detected" + ], + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Naming check not implemented for ['JSON']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['JSON']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.0, + "discovered_skills": [] +} \ No newline at end of file diff --git a/submissions/redhat/toolbox/2026-03-24T17-58-26-assessment.json b/submissions/redhat/toolbox/2026-03-24T17-58-26-assessment.json new file mode 100644 index 00000000..01b27a58 --- /dev/null +++ b/submissions/redhat/toolbox/2026-03-24T17-58-26-assessment.json @@ -0,0 +1,786 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.29.6", + "research_version": "1.0.1", + "assessment_timestamp": "2026-03-24T17:58:26.569076", + "assessment_timestamp_human": "March 24, 2026 at 5:58 PM", + "executed_by": "jrusz@92be7378c6bc", + "command": "/usr/local/bin/agentready assess /repo --config /agentready-config.yml --output-dir /reports", + "working_directory": "/tmp" + }, + "repository": { + "path": "/repo", + "name": "repo", + "url": "git@gitlab.com:redhat/rhel-ai/ci-cd/toolbox.git", + "branch": "main", + "commit_hash": "4b26acf789bdfa0602c5ff4439de9585a44aad88", + "languages": { + "Shell": 3 + }, + "total_files": 8, + "total_lines": 935 + }, + "timestamp": "2026-03-24T17:58:26.569076", + "overall_score": 24.8, + "certification_level": "Needs Improvement", + "attributes_assessed": 13, + "attributes_skipped": 5, + "attributes_total": 18, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "missing", + "threshold": "present", + "evidence": [ + "CLAUDE.md not found in repository root", + "AGENTS.md not found (alternative)" + ], + "remediation": { + "summary": "Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants", + "steps": [ + "Choose one of three approaches:", + " Option 1: Create standalone CLAUDE.md (>50 bytes) with project context", + " Option 2: Create AGENTS.md and symlink CLAUDE.md to it (cross-tool compatibility)", + " Option 3: Create AGENTS.md and reference it with @AGENTS.md in minimal CLAUDE.md", + "Add project overview and purpose", + "Document key architectural patterns", + "Specify coding standards and conventions", + "Include build/test/deployment commands", + "Add any project-specific context that helps AI assistants" + ], + "tools": [], + "commands": [ + "# Option 1: Standalone CLAUDE.md", + "touch CLAUDE.md", + "# Add content describing your project", + "", + "# Option 2: Symlink CLAUDE.md to AGENTS.md", + "touch AGENTS.md", + "# Add content to AGENTS.md", + "ln -s AGENTS.md CLAUDE.md", + "", + "# Option 3: @ reference in CLAUDE.md", + "echo '@AGENTS.md' > CLAUDE.md", + "touch AGENTS.md", + "# Add content to AGENTS.md" + ], + "examples": [ + "# Standalone CLAUDE.md (Option 1)\n\n## Overview\nBrief description of what this project does.\n\n## Architecture\nKey patterns and structure.\n\n## Development\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## Coding Standards\n- Use TypeScript strict mode\n- Follow ESLint configuration\n- Write tests for new features\n", + "# CLAUDE.md with @ reference (Option 3)\n@AGENTS.md\n", + "# AGENTS.md (shared by multiple tools)\n\n## Project Overview\nThis project implements a REST API for user management.\n\n## Architecture\n- Layered architecture: controllers, services, repositories\n- PostgreSQL database with SQLAlchemy ORM\n- FastAPI web framework\n\n## Development Workflow\n```bash\n# Setup\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\n# Run tests\npytest\n\n# Start server\nuvicorn app.main:app --reload\n```\n\n## Code Conventions\n- Use type hints for all functions\n- Follow PEP 8 style guide\n- Write docstrings for public APIs\n- Maintain >80% test coverage\n" + ], + "citations": [ + { + "source": "Anthropic", + "title": "Claude Code Documentation", + "url": "https://docs.anthropic.com/claude-code", + "relevance": "Official guidance on CLAUDE.md configuration" + }, + { + "source": "agents.md", + "title": "AGENTS.md Specification", + "url": "https://agents.md/", + "relevance": "Emerging standard for cross-tool AI assistant configuration" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "fail", + "score": 66.66666666666666, + "measured_value": "2/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 2/3 essential sections", + "Installation: \u2717", + "Usage: \u2713", + "Development: \u2713" + ], + "remediation": { + "summary": "Create or enhance README.md with essential sections", + "steps": [ + "Add project overview and description", + "Include installation/setup instructions", + "Document basic usage with examples", + "Add development/contributing guidelines", + "Include build and test commands" + ], + "tools": [], + "commands": [], + "examples": [ + "# Project Name\n\n## Overview\nWhat this project does and why it exists.\n\n## Installation\n```bash\npip install -e .\n```\n\n## Usage\n```bash\nmyproject --help\n```\n\n## Development\n```bash\n# Run tests\npytest\n\n# Format code\nblack .\n```\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "About READMEs", + "url": "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes", + "relevance": "Best practices for README structure" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Shell']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/ or project-named, tests/) present", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "0/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 0/2 standard directories", + "source directory: \u2717 (no src/ or project-named dir)", + "tests/: \u2717" + ], + "remediation": { + "summary": "Organize code into standard directories", + "steps": [ + "Create a source directory for your code", + "Option A: Use src/ layout (recommended for packages)", + "Option B: Use project-named directory (e.g., mypackage/)", + "Ensure your package has __init__.py", + "Create tests/ directory for test files", + "Add at least one test file" + ], + "tools": [], + "commands": [ + "# Option A: src layout", + "mkdir -p src/mypackage", + "touch src/mypackage/__init__.py", + "# ---", + "# Option B: flat layout (project-named)", + "mkdir -p mypackage", + "touch mypackage/__init__.py", + "# Create tests directory", + "mkdir -p tests", + "touch tests/__init__.py", + "touch tests/test_example.py" + ], + "examples": [ + "# src layout (recommended for distributable packages)\nproject/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n\n# flat layout (common in major projects like pandas, numpy)\nproject/\n\u251c\u2500\u2500 mypackage/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 module.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_module.py\n\u2514\u2500\u2500 pyproject.toml\n" + ], + "citations": [ + { + "source": "Python Packaging Authority", + "title": "src layout vs flat layout", + "url": "https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/", + "relevance": "Official guidance on Python project layouts" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Dependency Pinning for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Dependencies pinned to exact versions in lock files", + "criteria": "Lock file with pinned versions, updated within 6 months", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "lock file with pinned versions", + "evidence": [ + "No dependency lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "For npm: run 'npm install' (generates package-lock.json)", + "For Python: use 'pip freeze > requirements.txt' or poetry", + "For Ruby: run 'bundle install' (generates Gemfile.lock)" + ], + "tools": [ + "npm", + "pip", + "poetry", + "bundler" + ], + "commands": [ + "npm install # npm", + "pip freeze > requirements.txt # Python", + "poetry lock # Python with Poetry" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "dependency_security", + "name": "Dependency Security & Vulnerability Scanning", + "category": "Security", + "tier": 1, + "description": "Security scanning tools configured for dependencies and code", + "criteria": "Dependabot, Renovate, CodeQL, or SAST tools configured; secret detection enabled", + "default_weight": 0.04 + }, + "status": "fail", + "score": 0, + "measured_value": "No security scanning tools configured", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "No security scanning tools detected" + ], + "remediation": { + "summary": "Configure security scanning for dependencies and code", + "steps": [ + "Enable Dependabot in GitHub repository settings", + "Add .github/dependabot.yml configuration file", + "Or configure Renovate: add renovate.json to repository root", + "Set up CodeQL scanning for SAST", + "Add secret detection to pre-commit hooks", + "Configure language-specific security scanners" + ], + "tools": [ + "Dependabot", + "Renovate", + "CodeQL", + "detect-secrets", + "Bandit", + "Semgrep" + ], + "commands": [ + "gh repo edit --enable-security", + "pip install pre-commit detect-secrets", + "pre-commit install" + ], + "examples": [ + "# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: pip\n directory: /\n schedule:\n interval: weekly", + "# renovate.json\n{\n \"extends\": [\"config:base\"],\n \"schedule\": \"after 10pm every weekday\"\n}", + "# .pre-commit-config.yaml\nrepos:\n - repo: https://github.com/Yelp/detect-secrets\n rev: v1.4.0\n hooks:\n - id: detect-secrets" + ], + "citations": [ + { + "source": "OWASP", + "title": "OWASP Top 10", + "url": "https://owasp.org/www-project-top-ten/", + "relevance": "Industry-standard list of critical web application security risks" + }, + { + "source": "GitHub", + "title": "Security Best Practices", + "url": "https://docs.github.com/en/code-security", + "relevance": "Official GitHub security features and best practices documentation" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file with language-specific patterns", + "criteria": ".gitignore exists and includes language-specific patterns from GitHub templates", + "default_weight": 0.03 + }, + "status": "fail", + "score": 20.0, + "measured_value": "1/5 patterns", + "threshold": "\u226570% of language-specific patterns", + "evidence": [ + ".gitignore found (2318 bytes)", + "Pattern coverage: 1/5 (20%)", + "Missing 4 recommended patterns" + ], + "remediation": { + "summary": "Add missing language-specific ignore patterns", + "steps": [ + "Review GitHub's gitignore templates for your language", + "Add the 4 missing patterns", + "Ensure editor/IDE patterns are included" + ], + "tools": [], + "commands": [], + "examples": [ + "# Missing patterns:\n*.swp\n.vscode/\n*.swo\n.DS_Store" + ], + "citations": [ + { + "source": "GitHub", + "title": "gitignore Templates Collection", + "url": "https://github.com/github/gitignore", + "relevance": "Comprehensive collection of language-specific gitignore patterns" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Single command to set up development environment from fresh clone", + "criteria": "Single command (make setup, npm install, etc.) documented prominently", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0, + "measured_value": "multi-step setup", + "threshold": "single command", + "evidence": [ + "No clear setup command found in README", + "No Makefile or setup script found", + "Setup instructions not in first 3 sections" + ], + "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\n\n## Quick Start\n\n```bash\nmake setup # One command to set up development environment\nmake test # Run tests to verify setup\n```\n" + ], + "citations": [ + { + "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" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Files are reasonably sized for AI context windows", + "criteria": "<5% of files >500 lines, no files >1000 lines", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "0 huge, 0 large out of 1", + "threshold": "<5% files >500 lines, 0 files >1000 lines", + "evidence": [ + "All 1 source files are <500 lines" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_of_concerns", + "name": "Separation of Concerns", + "category": "Code Organization", + "tier": 2, + "description": "Code organized with single responsibility per module", + "criteria": "Feature-based organization, cohesive modules, low coupling", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "organization:100, cohesion:100, naming:100", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 0/1 files >500 lines", + "No catch-all modules (utils.py, helpers.py) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Documentation", + "category": "Documentation", + "tier": 2, + "description": "Documentation maximizes information density while minimizing token consumption", + "criteria": "README <500 lines with clear structure, bullet points over prose", + "default_weight": 0.03 + }, + "status": "fail", + "score": 70.0, + "measured_value": "127 lines, 23 headings, 8 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 127 lines (excellent)", + "Heading density: 18.1 per 100 lines (target: 3-5)", + "Only 8 bullet points (prefer bullets over prose)" + ], + "remediation": { + "summary": "Make documentation more concise and structured", + "steps": [ + "Break long README into multiple documents (docs/ directory)", + "Add clear Markdown headings (##, ###) for structure", + "Convert prose paragraphs to bullet points where possible", + "Add table of contents for documents >100 lines", + "Use code blocks instead of describing commands in prose", + "Move detailed content to wiki or docs/, keep README focused" + ], + "tools": [], + "commands": [ + "# Check README length", + "wc -l README.md", + "", + "# Count headings", + "grep -c '^#' README.md" + ], + "examples": [ + "# Good: Concise with structure\n\n## Quick Start\n```bash\npip install -e .\nagentready assess .\n```\n\n## Features\n- Fast repository scanning\n- HTML and Markdown reports\n- 25 agent-ready attributes\n\n## Documentation\nSee [docs/](docs/) for detailed guides.\n", + "# Bad: Verbose prose\n\nThis project is a tool that helps you assess your repository\nagainst best practices for AI-assisted development. It works by\nscanning your codebase and checking for various attributes that\nmake repositories more effective when working with AI coding\nassistants like Claude Code...\n\n[Many more paragraphs of prose...]\n" + ], + "citations": [ + { + "source": "ArXiv", + "title": "LongCodeBench: Evaluating Coding LLMs at 1M Context Windows", + "url": "https://arxiv.org/abs/2501.00343", + "relevance": "Research showing performance degradation with long contexts" + }, + { + "source": "Markdown Guide", + "title": "Basic Syntax", + "url": "https://www.markdownguide.org/basic-syntax/", + "relevance": "Best practices for Markdown formatting" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation", + "tier": 2, + "description": "Function, class, and module-level documentation using language-specific conventions", + "criteria": "\u226580% of public functions/classes have docstrings", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Shell']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Shell']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cicd_pipeline_visibility", + "name": "CI/CD Pipeline Visibility", + "category": "Testing & CI/CD", + "tier": 3, + "description": "Clear, well-documented CI/CD configuration files", + "criteria": "CI config with descriptive names, caching, parallelization", + "default_weight": 0.015 + }, + "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": { + "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\n\nname: CI Pipeline\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n lint:\n name: Lint Code\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip' # Caching\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run linters\n run: |\n black --check .\n isort --check .\n ruff check .\n\n test:\n name: Run Tests\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.11'\n cache: 'pip'\n\n - name: Install dependencies\n run: pip install -r requirements.txt\n\n - name: Run tests with coverage\n run: pytest --cov --cov-report=xml\n\n - name: Upload coverage reports\n uses: codecov/codecov-action@v3\n with:\n files: ./coverage.xml\n\n build:\n name: Build Package\n runs-on: ubuntu-latest\n needs: [lint, test] # Runs after lint/test pass\n steps:\n - uses: actions/checkout@v4\n\n - name: Build package\n run: python -m build\n\n - name: Upload build artifacts\n uses: actions/upload-artifact@v3\n with:\n name: dist\n path: dist/\n" + ], + "citations": [ + { + "source": "GitHub", + "title": "GitHub Actions Documentation", + "url": "https://docs.github.com/en/actions", + "relevance": "Official GitHub Actions guide" + }, + { + "source": "CircleCI", + "title": "CI/CD Best Practices", + "url": "https://circleci.com/blog/ci-cd-best-practices/", + "relevance": "Industry best practices for CI/CD" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic Naming", + "category": "Code Quality", + "tier": 3, + "description": "Systematic naming patterns following language conventions", + "criteria": "Language conventions followed, avoid generic names", + "default_weight": 0.015 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Naming check not implemented for ['Shell']" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "branch_protection", + "name": "Branch Protection Rules", + "category": "Git & Version Control", + "tier": 4, + "description": "Required status checks and review approvals before merging", + "criteria": "Branch protection enabled with status checks and required reviews", + "default_weight": 0.005 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Requires GitHub API integration for branch protection checks. Future implementation will verify: required status checks, required reviews, force push prevention, and branch update requirements." + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Linter configuration for detecting code smells and anti-patterns", + "criteria": "Language-specific linters configured (pylint, ESLint, RuboCop, etc.)", + "default_weight": 0.01 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "No linters configured" + ], + "remediation": { + "summary": "Configure 1 missing linter(s)", + "steps": [ + "Configure markdownlint for documentation quality" + ], + "tools": [ + "markdownlint" + ], + "commands": [ + "npm install --save-dev markdownlint-cli && touch .markdownlint.json" + ], + "examples": [ + "# .pylintrc example\n[MASTER]\nmax-line-length=100\n\n[MESSAGES CONTROL]\ndisable=C0111", + "# .eslintrc.json example\n{\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"no-console\": \"warn\"\n }\n}" + ], + "citations": [ + { + "source": "Pylint", + "title": "Pylint Documentation", + "url": "https://pylint.readthedocs.io/", + "relevance": "Official documentation for Pylint code analysis tool" + }, + { + "source": "ESLint", + "title": "ESLint Documentation", + "url": "https://eslint.org/docs/latest/", + "relevance": "Official documentation for ESLint JavaScript/TypeScript linter" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Container configuration for consistent development environments", + "criteria": "Dockerfile/Containerfile, docker-compose.yml, .dockerignore, multi-stage builds", + "default_weight": 0.01 + }, + "status": "pass", + "score": 40, + "measured_value": "40 points", + "threshold": "\u226570 points (Dockerfile + compose + .dockerignore)", + "evidence": [ + "\u2713 Containerfile present (Podman)", + "\u2139\ufe0f Single-stage build (consider multi-stage for smaller images)", + "\u2139\ufe0f No .dockerignore file (consider adding to reduce image size)" + ], + "remediation": { + "summary": "Improve container configuration", + "steps": [ + "Add docker-compose.yml for multi-service development", + "Create .dockerignore to exclude build artifacts and secrets", + "Consider multi-stage builds to reduce image size" + ], + "tools": [ + "docker", + "podman", + "docker-compose" + ], + "commands": [ + "docker build -t myapp .", + "docker-compose up -d" + ], + "examples": [ + "# .dockerignore example\n.git\n.venv\n__pycache__\n*.pyc\n.env\nnode_modules", + "# Multi-stage Dockerfile example\nFROM node:18 AS builder\nWORKDIR /app\nCOPY . .\nRUN npm ci && npm run build\n\nFROM node:18-alpine\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]" + ], + "citations": [ + { + "source": "Docker", + "title": "Dockerfile Best Practices", + "url": "https://docs.docker.com/develop/develop-images/dockerfile_best-practices/", + "relevance": "Official Docker guide for writing efficient and secure Dockerfiles" + } + ] + }, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [ + "test_coverage", + "conventional_commits", + "architecture_decisions", + "structured_logging", + "openapi_specs", + "issue_pr_templates", + "precommit_hooks" + ], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 0.0, + "discovered_skills": [] +} \ No newline at end of file