{"id":30770053,"url":"https://github.com/inciarmors/checkwise","last_synced_at":"2026-04-13T17:31:34.430Z","repository":{"id":312688085,"uuid":"1042615594","full_name":"inciarmors/checkwise","owner":"inciarmors","description":"Dynamic PR checklists based on file changes. Zero-code YAML config. GitHub Action for intelligent code review automation.","archived":false,"fork":false,"pushed_at":"2025-09-01T12:37:35.000Z","size":15331,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-01T12:38:40.174Z","etag":null,"topics":["automation","code-review","github-actions","pull-requests","review-process","status-checks","typescript","yaml"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inciarmors.png","metadata":{"files":{"readme":"README.MD","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-22T09:46:31.000Z","updated_at":"2025-09-01T12:37:39.000Z","dependencies_parsed_at":"2025-09-01T12:38:44.729Z","dependency_job_id":null,"html_url":"https://github.com/inciarmors/checkwise","commit_stats":null,"previous_names":["inciarmors/checkwise"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/inciarmors/checkwise","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inciarmors%2Fcheckwise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inciarmors%2Fcheckwise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inciarmors%2Fcheckwise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inciarmors%2Fcheckwise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inciarmors","download_url":"https://codeload.github.com/inciarmors/checkwise/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inciarmors%2Fcheckwise/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31762477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","code-review","github-actions","pull-requests","review-process","status-checks","typescript","yaml"],"created_at":"2025-09-04T23:03:07.254Z","updated_at":"2026-04-13T17:31:34.404Z","avatar_url":"https://github.com/inciarmors.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CheckWise\n\n**Dynamic Pull Request checklists based on changed file paths**\n\n[![GitHub Action](https://img.shields.io/badge/GitHub-Action-blue?logo=github-actions)](https://github.com/marketplace/actions/checkwise)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Tests](https://img.shields.io/github/actions/workflow/status/inciarmors/checkwise/ci.yml?branch=main\u0026label=tests)](https://github.com/inciarmors/checkwise/actions)\n[![Coverage](https://img.shields.io/badge/Coverage-79.3%25-brightgreen)](https://github.com/inciarmors/checkwise/actions)\n[![Self-Validation](https://img.shields.io/badge/Self--Validation-%20Active-success)](https://github.com/inciarmors/checkwise/actions/workflows/self-validation.yml)\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)\n[![Bundle Size](https://img.shields.io/badge/Bundle%20Size-690KB-orange)](https://github.com/inciarmors/checkwise)\n[![Node Version](https://img.shields.io/badge/Node-20+-brightgreen)](https://nodejs.org/)\n\n---\n\n## Executive Summary\n\nCheckWise is a production-ready GitHub Action that implements intelligent PR checklist automation through file-path-based rule engines. Designed for enterprise-scale development workflows, it eliminates manual checklist maintenance while providing enforcement mechanisms through GitHub Status Checks integration.\n\n**Architecture**: Event-driven TypeScript application with modular components for configuration parsing, pattern matching, GitHub API integration, and markdown generation.\n\n**Performance**: Sub-second execution, 690KB bundled size, optimized glob matching with micromatch, paginated API handling for large PRs.\n\n**Reliability**: 79.3% test coverage, 129 automated tests, comprehensive error handling, network resilience, rate limiting protection.\n\n### Technical Differentiators\n\n- **Zero-JavaScript Configuration**: Pure YAML declarative syntax eliminates code maintenance overhead\n- **Multi-Config Architecture**: Native support for team-specific, layered configuration files  \n- **Idempotent Operations**: Single comment updates prevent notification spam\n- **Enterprise Security**: Path traversal protection, input sanitization, secure token handling\n- **Status Check Integration**: Automatic merge protection with completion enforcement\n- **Schema-Driven Validation**: JSON Schema provides IDE autocompletion and real-time validation\n\n### Key Features\n\n- **Path-based precision**: Matches file paths, not content - eliminating false positives\n- **Zero-code configuration**: Pure YAML declarative rules, no JavaScript required  \n- **Idempotent updates**: Single comment that updates cleanly, never spam\n- **Multiple config files**: Support for team-specific or layered configuration files\n- **GitHub Status Checks**: Automatic merge blocking until checklist completion\n- **JSON Schema support**: Editor autocompletion and validation for configuration files\n- **Enterprise-grade validation**: Comprehensive input validation with actionable error messages\n- **High performance**: Fast glob matching vs. expensive content scanning\n\n---\n\n## Implementation Guide\n\n### Minimal Setup (\u003c 2 minutes)\n```yaml\n# .github/workflows/checkwise.yml\nname: CheckWise PR Automation\non:\n  pull_request:\n    types: [opened, synchronize]\n\njobs:\n  checklist:\n    runs-on: ubuntu-latest\n    permissions:\n      pull-requests: write    # Comment permissions\n      statuses: write         # Status check permissions\n    steps:\n      - uses: actions/checkout@v4\n      - uses: inciarmors/checkwise@v1\n        with:\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n          config-path: .github/checkwise.yml\n          create-status-check: true\n```\n\n### Configuration Schema (JSON Schema Validated)\n```yaml\n# .github/checkwise.yml - Esempio con template markdown custom\nchecklists:\n  # Backend Service Layer\n  - when: ['src/api/**/*.{ts,js}', 'src/services/**/*.{ts,js}', 'src/database/**']\n    require:\n      - 'OpenAPI/Swagger documentation updated'\n      - 'Database migration scripts reviewed'\n      - 'Unit tests achieve \u003e80% coverage'\n      - 'Integration tests include error scenarios'\n      - 'Security implications documented'\n      - 'Performance impact measured (APM/profiling)'\n      - 'Backward compatibility verified'\n    priority: 1\n    template: |\n      ### {{ruleTitle}} (Backend)\n      {{items}}\n\n  # Frontend Component Layer\n  - when: ['src/components/**/*.{tsx,jsx,vue}', 'src/pages/**/*.{tsx,jsx,vue}', 'src/styles/**']\n    require:\n      - 'Visual regression tests added/updated'\n      - 'Accessibility compliance verified (WCAG 2.1 AA)'\n      - 'Cross-browser testing completed (Chrome, Firefox, Safari)'\n      - 'Mobile responsiveness validated (320px-1920px)'\n      - 'Bundle size impact assessed (\u003c5% increase)'\n      - 'Loading states and error boundaries implemented'\n    priority: 2\n\noptions:\n  template: |\n    ## Custom Global Checklist\n    {{items}}\n```\n\n### Enterprise Multi-Config Architecture\n```yaml\n# .github/checkwise.yml - Main configuration\nchecklists:\n  # Include team-specific configurations\n  $include:\n    - teams/backend-team.yml\n    - teams/frontend-team.yml\n    - teams/devops-team.yml\n    - teams/security-team.yml\n  \n  # Global mandatory checks\n  mandatory:\n    patterns: ['**/*']\n    items:\n      - 'Issue/ticket reference included in PR description'\n      - 'Breaking changes documented in CHANGELOG.md'\n      - 'Documentation updated (if applicable)'\n\n# teams/backend-team.yml\nchecklists:\n  microservices:\n    patterns: ['services/**', 'api/**']\n    items:\n      - 'Circuit breaker patterns implemented'\n      - 'Distributed tracing correlation IDs added'\n      - 'Health check endpoints updated'\n```\n\n### Status Check Integration\n```yaml\n# Enable merge protection with completion enforcement\n- uses: inciarmors/checkwise@v1\n  with:\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n    config-path: .github/checkwise.yml\n    create-status-check: true        # Creates \"CheckWise\" status check\n    status-check-name: \"PR-Checklist\" # Custom status check name\n    comment-title: \"🔍 Code Review Checklist\" # Custom comment title\n```\n\n**Result**: PRs cannot be merged until all checklist items are manually checked off. The GitHub Status Check automatically updates from `failure` → `success` when completion is detected.\n\n---\n\n## Advanced Configuration\n\n### Multiple Config Files\n\nYou can specify multiple YAML config files for team-specific or layered rules. To do this, set the `config-path` input as a comma-separated list of files:\n\n```yaml\n      - uses: inciarmors/checkwise@v1\n        with:\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n          config-path: .github/checkwise.yml,team/checkwise-backend.yml,team/checkwise-frontend.yml\n```\n\n**How it works:**\n- All `checklists` from all files are combined.\n- `options` from later files override earlier ones if there are conflicts.\n- If any file is missing or invalid, the action fails with a clear error message.\n\nThis allows you to keep team, domain, or project-specific rules in separate files and combine them as needed.\n\n**Example structure:**\n```\n.github/checkwise.yml          # Base rules for all teams\nteam/checkwise-backend.yml     # Backend-specific rules\nteam/checkwise-frontend.yml    # Frontend-specific rules\nteam/checkwise-devops.yml      # DevOps-specific rules\n```\n\n---\n\n## Architecture\n\n### Core Components\n\n```\nsrc/\n├── main.ts          # Action entry point \u0026 orchestration\n├── config.ts        # YAML configuration parser \u0026 validation\n├── matcher.ts       # File path pattern matching (micromatch)\n├── github.ts        # GitHub API integration \u0026 error handling\n└── checklist.ts     # Markdown checklist generation\n```\n\n### Data Flow\n\n```\nPR Event → Validate Inputs → Load Config(s) → Get Changed Files → Match Patterns → Generate Checklist → Update Comment → Publish Status Check\n```\n\n### Input Validation Pipeline\n\n1. **GitHub Token Validation**: Format verification, security checks\n2. **Config Path Security**: Path traversal prevention, file existence validation\n3. **Multi-file Loading**: Comma-separated config file processing and merging\n4. **YAML Structure Validation**: 25+ granular validation rules with detailed error messages\n5. **GitHub Context Verification**: PR number, repository context validation\n6. **Error Handling**: Contextual messages with debugging hints and troubleshooting tips\n\n---\n\n## Configuration Reference\n\n### Basic Structure\n\n```yaml\nchecklists:\n  - when: [\"\u003cglob-patterns\u003e\"]     # File path patterns to match\n    require: [\"\u003cchecklist-items\u003e\"] # Required checklist items\n    optional: boolean              # Optional: default false\n\noptions:                          # Global options (optional)\n  branch_pattern: \"feature/*\"     # Only apply to specific branches\n  label_filter: [\"enhancement\"]   # Filter by PR labels\n  comment_header: \"Custom Header\" # Customize comment header\n```\n\n### Config Path Options\n\n| Input Method | Description | Example |\n|--------------|-------------|---------|\n| Single file | Default configuration | `.github/checkwise.yml` |\n| Multiple files | Comma-separated paths | `.github/checkwise.yml,team/backend.yml,team/frontend.yml` |\n| Custom path | Any valid YAML file | `config/pr-rules.yml` |\n\n### Advanced Glob Patterns\n\n```yaml\nchecklists:\n  # Multiple file types\n  - when: [\"**/*.{js,ts,jsx,tsx}\"]\n    require: [\"JavaScript/TypeScript standards followed\"]\n    \n  # Negation patterns\n  - when: [\"src/**/*.ts\", \"!**/*.test.ts\", \"!**/*.spec.ts\"]\n    require: [\"Production TypeScript code reviewed\"]\n    \n  # Nested directory matching\n  - when: [\"src/components/**/*.tsx\", \"src/pages/**/*.tsx\"]\n    require: [\"React component guidelines followed\"]\n    \n  # Exact file matching\n  - when: [\"package.json\", \"package-lock.json\"]\n    require: [\"Dependency security audit completed\"]\n```\n\n### Error Messages \u0026 Validation\n\nCheckWise provides comprehensive validation with specific, actionable error messages:\n\n```bash\n# Configuration validation\nError: Configuration file not found: \"team/missing.yml\". Create the file with your checklist rules or specify a different path with config-path.\n\n# YAML structure validation  \nError: Rule #2 in \"config.yml\": pattern #1 in \"when\" must be a string. Found: number\n\n# Options validation\nError: Config YAML in \"config.yml\": options.label_filter[1] must be a string. Found: number\n\n# Multi-file validation\nError: No valid checklists found in any config file.\n```\n\n**Validation categories:**\n- File existence and accessibility  \n- YAML syntax and structure\n- Rule object validation (when, require, optional)\n- Global options validation\n- Multi-file merging validation\n\n---\n\n## Use Cases\n\n### Frontend Development\n```yaml\n- when: [\"src/**/*.{tsx,jsx}\", \"components/**\", \"styles/**\"]\n  require:\n    - \"Visual regression tests passed\"\n    - \"Performance impact assessed\"\n    - \"Browser compatibility verified\"\n    - \"Accessibility standards met\"\n```\n\n### Infrastructure as Code\n```yaml\n- when: [\"terraform/**\", \"k8s/**/*.yaml\", \"infra/**\"]\n  require:\n    - \"Cost impact analysis completed\"\n    - \"Security review passed\"\n    - \"Rollback procedure documented\"\n    - \"Resource limits configured\"\n```\n\n### Database Operations\n```yaml\n- when: [\"migrations/**\", \"schema/**\", \"**/*.sql\"]\n  require:\n    - \"Migration tested on staging\"\n    - \"Performance impact assessed\"\n    - \"Rollback strategy defined\"\n    - \"DBA approval obtained\"\n```\n\n### API Development\n```yaml\n- when: [\"api/**\", \"routes/**\", \"**/*api*.ts\"]\n  require:\n    - \"OpenAPI specification updated\"\n    - \"Rate limiting configured\"\n    - \"Authentication tested\"\n    - \"Documentation published\"\n```\n\n---\n\n## Security \u0026 Error Handling\n\n### Input Validation\n- **Path traversal prevention**: Blocks `../` patterns in config paths\n- **Token format validation**: Validates GitHub token formats\n- **YAML injection protection**: Safe YAML parsing with js-yaml\n- **Repository context verification**: Ensures valid GitHub context\n\n### Error Handling\n- **Graceful degradation**: Continues operation on non-critical errors\n- **Rate limiting**: Built-in GitHub API rate limit handling\n- **Network resilience**: Automatic retry with exponential backoff\n- **Detailed logging**: Comprehensive debug information for troubleshooting\n\n### GitHub API Security\n```typescript\n// Safe API calls with retry logic\nasync function safeApiCall\u003cT\u003e(fn: () =\u003e Promise\u003cT\u003e, retries = 2): Promise\u003cT\u003e {\n  // Rate limit detection and handling\n  // Network error recovery\n  // Comprehensive error context\n}\n```\n\n---\n\n## Development\n\n### Prerequisites\n\n- Node.js 20+\n- TypeScript 5.9+\n- Jest 30+ (for testing)\n\n### Setup\n\n```bash\ngit clone https://github.com/inciarmors/checkwise\ncd checkwise\nnpm install\n```\n\n### Commands\n\n```bash\nnpm run dev          # TypeScript watch mode\nnpm test             # Run test suite (129 tests)\nnpm run test:watch   # Watch mode testing\nnpm run build        # Production build with ncc bundling\n```\n\n### Project Structure\n\n```\ncheckwise/\n├── src/                    # TypeScript source code\n│   ├── main.ts            # Action entry point \u0026 orchestration\n│   ├── config.ts          # Multi-file YAML configuration loader\n│   ├── matcher.ts         # File path pattern matching (micromatch)\n│   ├── github.ts          # GitHub API integration \u0026 status checks\n│   └── checklist.ts       # Markdown checklist generation\n├── __tests__/             # Jest test suite (129 tests, 79.3% coverage)\n├── schemas/               # JSON Schema for YAML autocompletion\n├── dist/                  # Compiled JavaScript (committed for GitHub Actions)\n├── examples/              # Configuration examples\n├── docs/                  # Additional documentation\n├── action.yml             # GitHub Action metadata\n├── package.json           # Dependencies \u0026 scripts\n└── tsconfig.json          # TypeScript configuration\n```\n\n### Testing\n\nThe project maintains **79.3% test coverage** with comprehensive validation across all components:\n\n```bash\n# Test statistics\nTest Suites: 9 passed, 9 total\nTests:       129 passed, 129 total\nCoverage:    79.3% statements, 77.3% branches, 66.7% functions\n```\n\nKey test areas:\n- **Input validation**: 35+ test cases covering all validation scenarios\n- **YAML configuration parsing**: 40+ test cases with multi-file support\n- **GitHub API integration**: 25+ test cases with error handling\n- **File pattern matching**: 15+ test cases with complex glob patterns  \n- **Error handling scenarios**: 20+ test cases for robust failure handling\n\n---\n\n## Documentation\n\n- **[Validation Guide](docs/VALIDATION.md)**: Comprehensive input validation reference\n- **[Configuration Examples](examples/)**: Real-world configuration patterns\n- **[API Reference](src/)**: TypeScript source code with full documentation\n\n---\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit changes (`git commit -m 'Add amazing feature'`)\n4. Test thoroughly (`npm test`)\n5. Push to branch (`git push origin feature/amazing-feature`)\n6. Open Pull Request\n\n### Code Quality Standards\n\n- **Test Coverage**: Maintain \u003e79% coverage (129 tests)\n- **TypeScript**: Strict mode with full type safety\n- **Linting**: ESLint with recommended rules\n- **Documentation**: Comprehensive JSDoc comments\n- **Self-Validation**: CheckWise validates its own Pull Requests\n\n### Self-Validation (Meta-Testing)\n\nCheckWise practices what it preaches - every Pull Request to this repository is validated by CheckWise itself using the configuration in [`.github/checkwise.yml`](.github/checkwise.yml). This ensures:\n\n- **Real-world testing**: Every feature is tested in production-like conditions\n- **Configuration validation**: Our example configs are battle-tested\n- **User experience verification**: We experience the same workflow as our users\n- **Quality assurance**: Critical changes are reviewed with appropriate checklists\n\nYou can see CheckWise in action on our own PRs, demonstrating the exact experience you'll get when using it in your projects.\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/inciarmors/checkwise/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/inciarmors/checkwise/discussions)  \n- **Documentation**: [Wiki](https://github.com/inciarmors/checkwise/wiki)\n\n---\n\n## Acknowledgments\n\n- [GitHub Actions Toolkit](https://github.com/actions/toolkit) - Robust GitHub Actions foundation\n- [Micromatch](https://github.com/micromatch/micromatch) - Fast and powerful glob matching\n- [js-yaml](https://github.com/nodeca/js-yaml) - Reliable YAML parsing\n- Community contributors and early adopters\n\n---\n\n**Built for developers, by developers**\n\n*Streamline your code review process with intelligent, contextual checklists.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finciarmors%2Fcheckwise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finciarmors%2Fcheckwise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finciarmors%2Fcheckwise/lists"}