diff --git a/submissions/red-hat-data-services/agentic-starter-kits/2026-05-19T18-40-31-assessment.json b/submissions/red-hat-data-services/agentic-starter-kits/2026-05-19T18-40-31-assessment.json new file mode 100644 index 00000000..3577ee9b --- /dev/null +++ b/submissions/red-hat-data-services/agentic-starter-kits/2026-05-19T18-40-31-assessment.json @@ -0,0 +1,952 @@ +{ + "schema_version": "1.0.0", + "metadata": { + "agentready_version": "2.30.1", + "research_version": "1.0.1", + "assessment_timestamp": "2026-05-19T14:35:14.002402", + "assessment_timestamp_human": "May 19, 2026 at 2:35 PM", + "executed_by": "tetikala@tetikala-mac", + "command": "/Users/tetikala/.pyenv/versions/3.12.12/bin/agentready assess .", + "working_directory": "/Users/tetikala/Documents/ASK" + }, + "repository": { + "path": "/Users/tetikala/Documents/ASK", + "name": "ASK", + "url": "https://github.com/red-hat-data-services/agentic-starter-kits.git", + "branch": "main", + "commit_hash": "7fb3ca4d216b08c9337bbba45eb81b27d83b4409", + "languages": { + "Markdown": 57, + "YAML": 76, + "Python": 180, + "Shell": 7, + "TOML": 13 + }, + "total_files": 420, + "total_lines": 48790 + }, + "timestamp": "2026-05-19T14:35:14.002402", + "overall_score": 63.7, + "certification_level": "Silver", + "attributes_assessed": 23, + "attributes_skipped": 2, + "attributes_total": 25, + "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": "@ reference to AGENTS.md", + "threshold": "present", + "evidence": [ + "CLAUDE.md found with @ reference to AGENTS.md", + "Referenced file contains 4186 bytes", + "AGENTS.md also present (cross-tool compatibility)" + ], + "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": "pass", + "score": 78.73665480427046, + "measured_value": "63.0%", + "threshold": "\u226580%", + "evidence": [ + "Typed functions: 354/562", + "Coverage: 63.0%" + ], + "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": "fail", + "score": 10, + "measured_value": "Security tools configured: pip-audit/safety", + "threshold": "\u226560 points (Dependabot/Renovate + SAST or multiple scanners)", + "evidence": [ + "\u2713 Python dependency scanner configured (pip-audit/safety)" + ], + "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": "test_coverage", + "name": "Test Coverage Requirements", + "category": "Testing & CI/CD", + "tier": 2, + "description": "Test coverage thresholds configured and enforced", + "criteria": ">80% code coverage", + "default_weight": 0.03 + }, + "status": "fail", + "score": 50.0, + "measured_value": "not configured", + "threshold": "configured with >80% threshold", + "evidence": [ + "Coverage config: \u2713", + "pytest-cov: \u2717" + ], + "remediation": { + "summary": "Configure test coverage with \u226580% threshold", + "steps": [ + "Install coverage tool (pytest-cov for Python, jest for JavaScript)", + "Configure coverage threshold in project config", + "Add coverage reporting to CI/CD pipeline", + "Run coverage locally before committing" + ], + "tools": [ + "pytest-cov", + "jest", + "vitest", + "coverage" + ], + "commands": [ + "# Python", + "pip install pytest-cov", + "pytest --cov=src --cov-report=term-missing --cov-fail-under=80", + "", + "# JavaScript", + "npm install --save-dev jest", + "npm test -- --coverage --coverageThreshold='{\\'global\\': {\\'lines\\': 80}}'" + ], + "examples": [ + "# Python - pyproject.toml\n[tool.pytest.ini_options]\naddopts = \"--cov=src --cov-report=term-missing\"\n\n[tool.coverage.report]\nfail_under = 80\n", + "// JavaScript - package.json\n{\n \"jest\": {\n \"coverageThreshold\": {\n \"global\": {\n \"lines\": 80,\n \"statements\": 80,\n \"functions\": 80,\n \"branches\": 80\n }\n }\n }\n}\n" + ], + "citations": [ + { + "source": "pytest-cov", + "title": "Coverage Configuration", + "url": "https://pytest-cov.readthedocs.io/", + "relevance": "pytest-cov configuration guide" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "precommit_hooks", + "name": "Pre-commit Hooks & CI/CD Linting", + "category": "Testing & CI/CD", + "tier": 2, + "description": "Pre-commit hooks configured for linting and formatting", + "criteria": ".pre-commit-config.yaml exists", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "configured", + "threshold": "configured", + "evidence": [ + ".pre-commit-config.yaml found" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "conventional_commits", + "name": "Conventional Commit Messages", + "category": "Git & Version Control", + "tier": 2, + "description": "Follows conventional commit format", + "criteria": "\u226580% of recent commits follow convention", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "configured", + "threshold": "configured", + "evidence": [ + "Commit linting configured" + ], + "remediation": null, + "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": 75.0, + "measured_value": "9/12 patterns", + "threshold": "\u226570% of language-specific patterns", + "evidence": [ + ".gitignore found (416 bytes)", + "Pattern coverage: 9/12 (75%)", + "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": "fail", + "score": 70, + "measured_value": "uv pip", + "threshold": "single command", + "evidence": [ + "Setup command found in README: 'uv pip'", + "Setup automation found: pyproject.toml", + "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": 90, + "measured_value": "0 huge, 7 large out of 180", + "threshold": "<5% files >500 lines, 0 files >1000 lines", + "evidence": [ + "Found 7 files 500-1000 lines (3.9% of 180 files)" + ], + "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": 80.83333333333333, + "measured_value": "organization:100, cohesion:96, naming:40", + "threshold": "\u226575 overall", + "evidence": [ + "Good directory organization (feature-based or flat)", + "File cohesion: 7/180 files >500 lines", + "Anti-pattern files found: utils.py, utils.py, utils.py" + ], + "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": 72.0, + "measured_value": "173 lines, 14 headings, 18 bullets", + "threshold": "<500 lines, structured format", + "evidence": [ + "README length: 173 lines (excellent)", + "Heading density: 8.1 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": 86.36363636363636, + "measured_value": "69.1%", + "threshold": "\u226580%", + "evidence": [ + "Documented items: 494/715", + "Coverage: 69.1%", + "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": "3.5", + "threshold": "<10.0", + "evidence": [ + "Average cyclomatic complexity: 3.5" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "architecture_decisions", + "name": "Architecture Decision Records (ADRs)", + "category": "Documentation Standards", + "tier": 3, + "description": "Lightweight documents capturing architectural decisions", + "criteria": "ADR directory with documented decisions", + "default_weight": 0.015 + }, + "status": "fail", + "score": 0.0, + "measured_value": "no ADR directory", + "threshold": "ADR directory with decisions", + "evidence": [ + "No ADR directory found (checked docs/adr/, .adr/, adr/, docs/decisions/)" + ], + "remediation": { + "summary": "Create Architecture Decision Records (ADRs) directory and document key decisions", + "steps": [ + "Create docs/adr/ directory in repository root", + "Use Michael Nygard ADR template or MADR format", + "Document each significant architectural decision", + "Number ADRs sequentially (0001-*.md, 0002-*.md)", + "Include Status, Context, Decision, and Consequences sections", + "Update ADR status when decisions are revised (Superseded, Deprecated)" + ], + "tools": [ + "adr-tools", + "log4brains" + ], + "commands": [ + "# Create ADR directory", + "mkdir -p docs/adr", + "", + "# Create first ADR using template", + "cat > docs/adr/0001-use-architecture-decision-records.md << 'EOF'", + "# 1. Use Architecture Decision Records", + "", + "Date: 2025-11-22", + "", + "## Status", + "Accepted", + "", + "## Context", + "We need to record architectural decisions made in this project.", + "", + "## Decision", + "We will use Architecture Decision Records (ADRs) as described by Michael Nygard.", + "", + "## Consequences", + "- Decisions are documented with context", + "- Future contributors understand rationale", + "- ADRs are lightweight and version-controlled", + "EOF" + ], + "examples": [ + "# Example ADR Structure\n\n```markdown\n# 2. Use PostgreSQL for Database\n\nDate: 2025-11-22\n\n## Status\nAccepted\n\n## Context\nWe need a relational database for complex queries and ACID transactions.\nTeam has PostgreSQL experience. Need full-text search capabilities.\n\n## Decision\nUse PostgreSQL 15+ as primary database.\n\n## Consequences\n- Positive: Robust ACID, full-text search, team familiarity\n- Negative: Higher resource usage than SQLite\n- Neutral: Need to manage migrations, backups\n```\n" + ], + "citations": [ + { + "source": "Michael Nygard", + "title": "Documenting Architecture Decisions", + "url": "https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions", + "relevance": "Original ADR format and rationale" + }, + { + "source": "GitHub adr/madr", + "title": "Markdown ADR (MADR) Template", + "url": "https://github.com/adr/madr", + "relevance": "Modern ADR template with examples" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "issue_pr_templates", + "name": "Issue & Pull Request Templates", + "category": "Repository Structure", + "tier": 3, + "description": "Standardized templates for issues and PRs", + "criteria": "PR template and issue templates in .github/", + "default_weight": 0.015 + }, + "status": "pass", + "score": 100, + "measured_value": "PR:True, Issues:2", + "threshold": "PR template + \u22652 issue templates", + "evidence": [ + "PR template found", + "Issue templates found: 2 templates" + ], + "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: .github/workflows/code-quality.yml, .github/workflows/pr-labeler.yml, .github/workflows/agent-tests.yml, .github/workflows/agent-deployment-test.yaml", + "Descriptive job/step names found", + "No caching detected", + "Parallel job execution 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": "pass", + "score": 100.0, + "measured_value": "functions:100%, classes:100%", + "threshold": "\u226575% compliance", + "evidence": [ + "Functions: 147/147 follow snake_case (100.0%)", + "Classes: 41/41 follow PascalCase (100.0%)", + "No generic names (temp, data, obj) detected" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "structured_logging", + "name": "Structured Logging", + "category": "Code Quality", + "tier": 3, + "description": "Logging in structured format (JSON) with consistent fields", + "criteria": "Structured logging library configured (structlog, winston, zap)", + "default_weight": 0.015 + }, + "status": "fail", + "score": 0.0, + "measured_value": "not configured", + "threshold": "structured logging library", + "evidence": [ + "No structured logging library found", + "Checked files: pyproject.toml", + "Using built-in logging module (unstructured)" + ], + "remediation": { + "summary": "Add structured logging library for machine-parseable logs", + "steps": [ + "Choose structured logging library (structlog for Python, winston for Node.js)", + "Install library and configure JSON formatter", + "Add standard fields: timestamp, level, message, context", + "Include request context: request_id, user_id, session_id", + "Use consistent field naming (snake_case for Python)", + "Never log sensitive data (passwords, tokens, PII)", + "Configure different formats for dev (pretty) and prod (JSON)" + ], + "tools": [ + "structlog", + "winston", + "zap" + ], + "commands": [ + "# Install structlog", + "pip install structlog", + "", + "# Configure structlog", + "# See examples for configuration" + ], + "examples": [ + "# Python with structlog\nimport structlog\n\n# Configure structlog\nstructlog.configure(\n processors=[\n structlog.stdlib.add_log_level,\n structlog.processors.TimeStamper(fmt=\"iso\"),\n structlog.processors.JSONRenderer()\n ]\n)\n\nlogger = structlog.get_logger()\n\n# Good: Structured logging\nlogger.info(\n \"user_login\",\n user_id=\"123\",\n email=\"user@example.com\",\n ip_address=\"192.168.1.1\"\n)\n\n# Bad: Unstructured logging\nlogger.info(f\"User {user_id} logged in from {ip}\")\n" + ], + "citations": [ + { + "source": "structlog", + "title": "structlog Documentation", + "url": "https://www.structlog.org/en/stable/", + "relevance": "Python structured logging library" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "openapi_specs", + "name": "OpenAPI/Swagger Specifications", + "category": "API Documentation", + "tier": 3, + "description": "Machine-readable API documentation in OpenAPI format", + "criteria": "OpenAPI 3.x spec with complete endpoint documentation", + "default_weight": 0.015 + }, + "status": "fail", + "score": 0.0, + "measured_value": "no OpenAPI spec", + "threshold": "OpenAPI 3.x spec present", + "evidence": [ + "No OpenAPI specification found", + "Searched recursively for: openapi.yaml, openapi.yml, openapi.json, swagger.yaml, swagger.yml, swagger.json" + ], + "remediation": { + "summary": "Create OpenAPI specification for API endpoints", + "steps": [ + "Create openapi.yaml in repository root", + "Define OpenAPI version 3.x", + "Document all API endpoints with full schemas", + "Add request/response examples", + "Define security schemes (API keys, OAuth, etc.)", + "Validate spec with Swagger Editor or Spectral", + "Generate API documentation with Swagger UI or ReDoc" + ], + "tools": [ + "swagger-editor", + "spectral", + "openapi-generator" + ], + "commands": [ + "# Install OpenAPI validator", + "npm install -g @stoplight/spectral-cli", + "", + "# Validate spec", + "spectral lint openapi.yaml", + "", + "# Generate client SDK", + "npx @openapitools/openapi-generator-cli generate \\", + " -i openapi.yaml \\", + " -g python \\", + " -o client/" + ], + "examples": [ + "# openapi.yaml - Minimal example\nopenapi: 3.1.0\ninfo:\n title: My API\n version: 1.0.0\n description: API for managing users\n\nservers:\n - url: https://api.example.com/v1\n\npaths:\n /users/{userId}:\n get:\n summary: Get user by ID\n parameters:\n - name: userId\n in: path\n required: true\n schema:\n type: string\n responses:\n '200':\n description: User found\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/User'\n '404':\n description: User not found\n\ncomponents:\n schemas:\n User:\n type: object\n required:\n - id\n - email\n properties:\n id:\n type: string\n example: \"user_123\"\n email:\n type: string\n format: email\n example: \"user@example.com\"\n name:\n type: string\n example: \"John Doe\"\n" + ], + "citations": [ + { + "source": "OpenAPI Initiative", + "title": "OpenAPI Specification", + "url": "https://spec.openapis.org/oas/v3.1.0", + "relevance": "Official OpenAPI 3.1 specification" + }, + { + "source": "Swagger", + "title": "API Documentation Best Practices", + "url": "https://swagger.io/resources/articles/best-practices-in-api-documentation/", + "relevance": "Guide to writing effective API docs" + } + ] + }, + "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": 83.33333333333334, + "measured_value": "pylint, ruff, actionlint", + "threshold": "\u226560% of applicable linters configured", + "evidence": [ + "Linters configured: pylint, ruff, actionlint", + "Coverage: 50/60 points (83%)" + ], + "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": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Not applicable to ['Markdown', 'YAML', 'Python', 'Shell', 'TOML']" + ], + "remediation": null, + "error_message": null + } + ], + "config": { + "weights": {}, + "excluded_attributes": [], + "language_overrides": {}, + "output_dir": null, + "report_theme": "default", + "custom_theme": null + }, + "duration_seconds": 1.2, + "discovered_skills": [] +} \ No newline at end of file