diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..6d8207d --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,58 @@ +--- +name: Issue Report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' +--- + +## Description + +A clear and concise description of the issue. + +## Type of Issue + +- [ ] Bug report +- [ ] Feature request +- [ ] Documentation improvement +- [ ] Question +- [ ] Other + +## Current Behavior + +What is currently happening? + +## Expected Behavior + +What should be happening? + +## Steps to Reproduce + +For bug reports, provide steps to reproduce the behavior: + +1. Go to '...' +2. Run command '...' +3. See error + +## Environment + +- OS: [e.g., Ubuntu 22.04, macOS 13, Windows 11] +- Node.js version (if applicable): [e.g., 18.17.0] +- Python version (if applicable): [e.g., 3.11.0] +- Package manager: [e.g., npm, yarn, pip] +- Project version/commit: [e.g., v1.0.0, commit abc123] + +## Additional Context + +Add any other context about the problem here. Include: + +- Error messages or logs +- Screenshots (if applicable) +- Related issues or PRs +- Possible solutions you've considered + +## Checklist + +- [ ] I have searched for existing issues +- [ ] I have provided all requested information +- [ ] I have included error messages/logs if applicable diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..22c2b08 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,89 @@ +## Description + + + +## Related Issue + + + +Fixes # + +## Type of Change + + + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Code refactoring +- [ ] Performance improvement +- [ ] Dependency update +- [ ] CI/CD update +- [ ] Other (please describe): + +## Changes Made + + + +- +- +- + +## Testing + + + +- [ ] All existing tests pass +- [ ] Added new tests for changes +- [ ] Manual testing completed +- [ ] No tests required (documentation, comments, etc.) + +### Test Details + + + +``` +# Commands run for testing +npm test +# or +pytest +``` + +## Checklist + + + +- [ ] My code follows the project's coding standards +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published +- [ ] I have checked my code and corrected any misspellings +- [ ] No secrets or credentials are committed +- [ ] Branch is up to date with base branch + +## Screenshots (if applicable) + + + +## Additional Notes + + + +## Reviewer Notes + + + +--- + +**For Reviewers:** + +- [ ] Code review completed +- [ ] Tests verified +- [ ] Documentation reviewed +- [ ] No security concerns +- [ ] Ready to merge diff --git a/.github/workflows/blank.yml b/.github/workflows/blank.yml index 9ddbd2e..0aa38b7 100644 --- a/.github/workflows/blank.yml +++ b/.github/workflows/blank.yml @@ -3,12 +3,12 @@ name: CI # Controls when the action will run. Triggers the workflow on push or pull request -# events but only for the master branch +# events but only for the master or main branch on: push: - branches: [ master ] + branches: [ master, main ] pull_request: - branches: [ master ] + branches: [ master, main ] # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: @@ -20,7 +20,7 @@ jobs: # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 # Runs a single command using the runners shell - name: Run a one-line script diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..e73b7a6 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,56 @@ +name: "CodeQL Analysis" + +on: + push: + branches: [master, main] + pull_request: + branches: [master, main] + schedule: + # Run at 6:00 UTC every Monday + - cron: '0 6 * * 1' + workflow_dispatch: + +permissions: + actions: read + contents: read + security-events: write + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + timeout-minutes: 360 + + strategy: + fail-fast: false + matrix: + # CodeQL supports: 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby', 'swift' + # Auto-detect languages in the repository + # Override this matrix if you want to analyze specific languages + language: [javascript, python] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + # queries: security-extended,security-and-quality + + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + # If autobuild fails, you can replace it with custom build steps: + # - name: Build + # run: | + # make bootstrap + # make release + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: "/language:${{matrix.language}}" diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 0000000..7282b1e --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,29 @@ +name: "Dependency Review" + +on: + pull_request: + branches: [master, main] + +permissions: + contents: read + pull-requests: write + +jobs: + dependency-review: + name: Dependency Review + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Dependency Review + uses: actions/dependency-review-action@v4 + with: + # Fail the action if there are vulnerabilities + fail-on-severity: moderate + # Comment on the PR with the results + comment-summary-in-pr: true + # Allow licenses (customize based on your policy) + allow-licenses: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD + # Deny licenses (customize based on your policy) + deny-licenses: GPL-3.0, AGPL-3.0 diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..b52611a --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,155 @@ +name: Deploy + +on: + push: + branches: [master, main] + workflow_dispatch: + inputs: + environment: + description: 'Environment to deploy to' + required: true + type: choice + options: + - dev + - stage + - prod + +permissions: + contents: read + id-token: write # Required for OIDC authentication + +jobs: + deploy: + name: Deploy to ${{ github.event.inputs.environment || 'dev' }} + runs-on: ubuntu-latest + environment: ${{ github.event.inputs.environment || 'dev' }} + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set cloud role based on environment + id: set-role + run: | + ENV="${{ github.event.inputs.environment || 'dev' }}" + case "$ENV" in + dev) + echo "cloud_role=arn:aws:iam::ACCOUNT_ID:role/github-actions-dev" >> $GITHUB_OUTPUT + ;; + stage) + echo "cloud_role=arn:aws:iam::ACCOUNT_ID:role/github-actions-stage" >> $GITHUB_OUTPUT + ;; + prod) + echo "cloud_role=arn:aws:iam::ACCOUNT_ID:role/github-actions-prod" >> $GITHUB_OUTPUT + ;; + *) + echo "cloud_role=arn:aws:iam::ACCOUNT_ID:role/github-actions-dev" >> $GITHUB_OUTPUT + ;; + esac + + - name: Configure AWS credentials (OIDC) + # Placeholder for AWS OIDC authentication + # Uncomment and configure when AWS is set up + # uses: aws-actions/configure-aws-credentials@v4 + # with: + # role-to-assume: ${{ steps.set-role.outputs.cloud_role }} + # aws-region: us-east-1 + run: | + echo "OIDC authentication placeholder" + echo "Environment: ${{ github.event.inputs.environment || 'dev' }}" + echo "Cloud role: ${{ steps.set-role.outputs.cloud_role }}" + + - name: Configure GCP credentials (OIDC) + # Placeholder for GCP OIDC authentication + # Uncomment and configure when GCP is set up + # uses: google-github-actions/auth@v2 + # with: + # workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID' + # service_account: 'github-actions@PROJECT_ID.iam.gserviceaccount.com' + run: | + echo "GCP OIDC authentication placeholder" + + - name: Configure Azure credentials (OIDC) + # Placeholder for Azure OIDC authentication + # Uncomment and configure when Azure is set up + # uses: azure/login@v1 + # with: + # client-id: ${{ secrets.AZURE_CLIENT_ID }} + # tenant-id: ${{ secrets.AZURE_TENANT_ID }} + # subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} + run: | + echo "Azure OIDC authentication placeholder" + + - name: Set environment variables + run: | + echo "Setting up environment variables (use GitHub Secrets/Variables in production)" + # WEB3_RPC_URL: ${{ vars.WEB3_RPC_URL || secrets.WEB3_RPC_URL }} + # OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + # SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }} + # DISCORD_BOT_TOKEN: ${{ secrets.DISCORD_BOT_TOKEN }} + # DB_URL: ${{ secrets.DB_URL }} + # S3_BUCKET: ${{ vars.S3_BUCKET }} + echo "Environment variables configured" + + - name: Determine package manager + id: package-manager + run: | + if [ -f "yarn.lock" ]; then + echo "manager=yarn" >> $GITHUB_OUTPUT + elif [ -f "package-lock.json" ]; then + echo "manager=npm" >> $GITHUB_OUTPUT + else + echo "manager=" >> $GITHUB_OUTPUT + fi + + - name: Setup Node.js + if: steps.package-manager.outputs.manager != '' + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: ${{ steps.package-manager.outputs.manager }} + + - name: Install dependencies + run: | + if [ -f "package.json" ]; then + if [ -f "yarn.lock" ]; then + yarn install --frozen-lockfile + elif [ -f "package-lock.json" ]; then + npm ci + else + npm install + fi + fi + + - name: Build application + run: | + if [ -f "package.json" ] && grep -q '"build"' package.json; then + if [ -f "yarn.lock" ]; then + yarn build + else + npm run build + fi + else + echo "No build script found, skipping..." + fi + + - name: Run deployment + run: | + echo "Deployment to ${{ github.event.inputs.environment || 'dev' }} would happen here" + echo "Configure your deployment steps based on your infrastructure" + # Examples: + # - Deploy to AWS: aws s3 sync dist/ s3://$S3_BUCKET + # - Deploy to GCP: gcloud app deploy + # - Deploy to Azure: az webapp deploy + # - Deploy to Kubernetes: kubectl apply -f k8s/ + # - Deploy to serverless: serverless deploy --stage ${{ github.event.inputs.environment }} + + - name: Notify deployment status + if: always() + run: | + echo "Deployment ${{ job.status }}" + # Add notification integrations here: + # - Slack webhook: curl -X POST $SLACK_WEBHOOK -d '{"text":"Deployment ${{ job.status }}"}' + # - Discord webhook: similar to Slack + # - Email notification + # - etc. diff --git a/.github/workflows/lint-test.yml b/.github/workflows/lint-test.yml new file mode 100644 index 0000000..846cfb2 --- /dev/null +++ b/.github/workflows/lint-test.yml @@ -0,0 +1,141 @@ +name: Lint and Test + +on: + push: + branches: [master, main] + pull_request: + branches: [master, main] + +permissions: + contents: read + +jobs: + lint-test-node: + name: Node.js Lint & Test + runs-on: ubuntu-latest + if: ${{ hashFiles('package.json', 'yarn.lock', 'package-lock.json') != '' }} + + strategy: + matrix: + node-version: [18, 20] + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: ${{ hashFiles('yarn.lock') != '' && 'yarn' || 'npm' }} + + - name: Install dependencies (npm) + if: ${{ hashFiles('package-lock.json') != '' }} + run: npm ci + + - name: Install dependencies (yarn) + if: ${{ hashFiles('yarn.lock') != '' }} + run: yarn install --frozen-lockfile + + - name: Run linter + run: | + if grep -q '"lint"' package.json; then + if [ -f "yarn.lock" ]; then + yarn lint + else + npm run lint + fi + else + echo "No lint script found, skipping..." + fi + + - name: Run formatter check + run: | + if grep -q '"format"' package.json; then + if [ -f "yarn.lock" ]; then + yarn format --check || yarn format:check || true + else + npm run format --check || npm run format:check || true + fi + else + echo "No format script found, skipping..." + fi + + - name: Run tests + run: | + if grep -q '"test"' package.json; then + if [ -f "yarn.lock" ]; then + yarn test + else + npm test + fi + else + echo "No test script found, skipping..." + fi + + lint-test-python: + name: Python Lint & Test + runs-on: ubuntu-latest + if: ${{ hashFiles('requirements.txt', 'pyproject.toml', 'setup.py', '**/*.py') != '' }} + + strategy: + matrix: + python-version: ['3.9', '3.10', '3.11'] + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + cache: 'pip' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + if [ -f requirements.txt ]; then + pip install -r requirements.txt + fi + if [ -f requirements-dev.txt ]; then + pip install -r requirements-dev.txt + fi + # Install linting and testing tools if not already installed + pip install flake8 black pytest 2>/dev/null || echo "Some tools already installed" + + - name: Lint with flake8 + run: | + # Stop the build if there are Python syntax errors or undefined names + flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics + # Exit-zero treats all errors as warnings + flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics + + - name: Check formatting with black + # Note: continue-on-error allows the workflow to pass even with formatting issues + # Remove this flag to enforce strict formatting standards + run: | + black --check . + continue-on-error: true + + - name: Run tests with pytest + run: | + if [ -d "tests" ] || find . -name "test_*.py" | grep -q .; then + pytest + else + echo "No tests found, skipping..." + fi + + lint-status: + name: Lint & Test Status + runs-on: ubuntu-latest + needs: [lint-test-node, lint-test-python] + if: always() + steps: + - name: Check status + run: | + echo "Lint and test jobs completed" + if [ "${{ needs.lint-test-node.result }}" == "failure" ] || [ "${{ needs.lint-test-python.result }}" == "failure" ]; then + echo "One or more jobs failed" + exit 1 + fi diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..8c1cfc4 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,17 @@ +# Default code owners for the repository +# These owners will be requested for review when someone opens a pull request + +# Global fallback - all files +* @lippytm + +# GitHub Actions workflows +/.github/workflows/ @lippytm + +# Security and governance files +/SECURITY.md @lippytm +/CONTRIBUTING.md @lippytm +/LICENSE @lippytm +/CODEOWNERS @lippytm + +# Documentation +*.md @lippytm diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..44d032d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,258 @@ +# Contributing to Transparency Logic Time Machine Bots + +Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [How to Contribute](#how-to-contribute) +- [Development Workflow](#development-workflow) +- [Pull Request Process](#pull-request-process) +- [Testing Guidelines](#testing-guidelines) +- [Coding Standards](#coding-standards) +- [Commit Message Guidelines](#commit-message-guidelines) + +## Code of Conduct + +Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive environment for all contributors. + +## Getting Started + +1. **Fork the repository** to your own GitHub account +2. **Clone your fork** locally: + ```bash + git clone https://github.com/YOUR_USERNAME/Transparency-Logic-Time-Machine-Bots-.git + cd Transparency-Logic-Time-Machine-Bots- + ``` +3. **Add the upstream remote**: + ```bash + git remote add upstream https://github.com/lippytm/Transparency-Logic-Time-Machine-Bots-.git + ``` +4. **Create a branch** for your changes: + ```bash + git checkout -b feature/your-feature-name + ``` + +## How to Contribute + +### Reporting Bugs + +- Check if the bug has already been reported in [Issues](https://github.com/lippytm/Transparency-Logic-Time-Machine-Bots-/issues) +- If not, create a new issue using the issue template +- Provide as much detail as possible: steps to reproduce, expected behavior, actual behavior, environment details + +### Suggesting Features + +- Check if the feature has already been suggested +- Create a new issue describing the feature and its benefits +- Be open to discussion and feedback + +### Contributing Code + +1. Pick an issue to work on or create a new one +2. Comment on the issue to let others know you're working on it +3. Follow the development workflow below +4. Submit a pull request when ready + +## Development Workflow + +### Setting Up Your Development Environment + +#### For Node.js/TypeScript projects: + +```bash +# Install dependencies +npm install +# or +yarn install + +# Run linter +npm run lint +# or +yarn lint + +# Run tests +npm test +# or +yarn test +``` + +#### For Python projects: + +```bash +# Create a virtual environment +python -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate + +# Install dependencies +pip install -r requirements.txt +pip install -r requirements-dev.txt # If it exists + +# Run linter +flake8 . +black --check . + +# Run tests +pytest +``` + +### Making Changes + +1. **Keep changes focused**: Each PR should address a single concern +2. **Write tests**: Add tests for new features or bug fixes +3. **Update documentation**: Update README, docstrings, or comments as needed +4. **Follow coding standards**: See section below + +## Pull Request Process + +### Before Submitting + +- [ ] Code follows the project's coding standards +- [ ] All tests pass locally +- [ ] New tests added for new features/bug fixes +- [ ] Documentation updated if needed +- [ ] Commits follow the commit message guidelines +- [ ] Branch is up to date with master/main +- [ ] No merge conflicts +- [ ] Self-review completed + +### PR Checklist + +When you submit a PR, please ensure: + +- [ ] **Title** is descriptive and follows conventional commit format (e.g., "feat: add new feature", "fix: resolve bug") +- [ ] **Description** clearly explains the changes and links to related issues +- [ ] **Tests** pass in CI/CD pipeline +- [ ] **No secrets or credentials** are committed +- [ ] **Code review** has been requested from maintainers +- [ ] **Documentation** is updated if the PR changes behavior + +### Branch Protection + +The `master` and `main` branches are protected with the following rules: + +- Pull requests are required before merging +- At least one approval is required +- Status checks must pass: + - Lint and Test workflow + - CodeQL Analysis + - Dependency Review (for PRs) +- Branches must be up to date before merging + +## Testing Guidelines + +### Writing Tests + +- **Unit tests**: Test individual functions/methods in isolation +- **Integration tests**: Test interactions between components +- **Test coverage**: Aim for meaningful test coverage, especially for critical paths + +### Running Tests + +```bash +# Node.js/TypeScript +npm test +yarn test + +# Python +pytest +pytest --cov # With coverage + +# Specific test file +pytest tests/test_specific.py +``` + +### Test Requirements + +- All new features must include tests +- Bug fixes should include a regression test +- Tests should be deterministic and not flaky +- Tests should be fast and focused + +## Coding Standards + +### General Guidelines + +- Write clear, readable, and maintainable code +- Follow the principle of least surprise +- Keep functions/methods small and focused +- Use meaningful variable and function names +- Add comments for complex logic, but prefer self-documenting code + +### JavaScript/TypeScript + +- Follow the existing code style in the project +- Use ESLint and Prettier for formatting +- Use TypeScript types where applicable +- Prefer `const` over `let`, avoid `var` + +### Python + +- Follow PEP 8 style guide +- Use type hints for function signatures +- Use Black for code formatting +- Use Flake8 for linting +- Maximum line length: 127 characters + +### Documentation + +- Add JSDoc/docstrings for public APIs +- Update README for user-facing changes +- Include inline comments for complex algorithms +- Keep documentation up to date with code changes + +## Commit Message Guidelines + +We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +(): + + + +