diff --git a/.github/WORKFLOWS.md b/.github/WORKFLOWS.md new file mode 100644 index 00000000..d2f57d11 --- /dev/null +++ b/.github/WORKFLOWS.md @@ -0,0 +1,221 @@ +# GitHub Workflows Documentation + +This document describes all the GitHub Actions workflows configured for the ObjectQL repository. + +## Core CI/CD Workflows + +### ๐Ÿ”จ [ci.yml](workflows/ci.yml) +**Purpose:** Main continuous integration pipeline +**Triggers:** Push to `main`, Pull Requests +**What it does:** +- Runs on Node.js 18.x and 20.x +- Installs dependencies with pnpm +- Builds all packages +- Runs test suite across all packages +- Sets up Redis and MongoDB for driver tests + +### ๐Ÿ“Š [coverage.yml](workflows/coverage.yml) โœจ NEW +**Purpose:** Test coverage tracking and reporting +**Triggers:** Push to `main`, Pull Requests +**What it does:** +- Runs tests with coverage collection +- Uploads coverage reports to Codecov +- Provides coverage insights on PRs +- Tracks coverage trends over time + +### โœ… [typecheck.yml](workflows/typecheck.yml) +**Purpose:** TypeScript type checking +**Triggers:** Push to `main`, Pull Requests +**What it does:** +- Runs TypeScript compiler in build mode +- Ensures no type errors across the monorepo +- Fast feedback on type safety + +## Release & Publishing + +### ๐Ÿš€ [release.yml](workflows/release.yml) +**Purpose:** Automated package publishing +**Triggers:** Push to `main` +**What it does:** +- Uses Changesets for version management +- Creates release PRs automatically +- Publishes packages to npm when merged +- Requires NPM_TOKEN secret + +### ๐Ÿ“ [changelog-preview.yml](workflows/changelog-preview.yml) โœจ NEW +**Purpose:** Preview changelog before release +**Triggers:** Pull Requests +**What it does:** +- Shows what changes will be included in next release +- Reminds contributors to add changesets +- Comments on PRs with changelog preview + +## Code Quality & Security + +### ๐Ÿ”’ [codeql.yml](workflows/codeql.yml) +**Purpose:** Security scanning with CodeQL +**Triggers:** Push to `main`, Pull Requests, Weekly schedule +**What it does:** +- Scans JavaScript/TypeScript code for vulnerabilities +- Runs security analysis +- Creates security alerts for issues found + +### ๐Ÿ” [dependency-review.yml](workflows/dependency-review.yml) +**Purpose:** Dependency security review +**Triggers:** Pull Requests +**What it does:** +- Reviews new/updated dependencies +- Checks for known vulnerabilities +- Fails on moderate or higher severity issues +- Comments on PRs with findings + +### โœ“ [validate-metadata.yml](workflows/validate-metadata.yml) +**Purpose:** Validate ObjectQL metadata files +**Triggers:** Changes to `*.object.yml`, `*.validation.yml`, etc. +**What it does:** +- Validates YAML syntax for metadata files +- Ensures metadata follows ObjectQL schema +- Prevents invalid metadata from being merged + +## Documentation + +### ๐Ÿ“š [deploy-docs.yml](workflows/deploy-docs.yml) +**Purpose:** Deploy documentation to GitHub Pages +**Triggers:** Push to `main` (docs changes), Manual dispatch +**What it does:** +- Builds VitePress documentation site +- Deploys to GitHub Pages +- Makes docs available at objectql.org + +### ๐Ÿ”— [link-checker.yml](workflows/link-checker.yml) โœจ NEW +**Purpose:** Check for broken links in documentation +**Triggers:** Push/PR with doc changes, Weekly schedule, Manual +**What it does:** +- Scans all Markdown files for links +- Checks if links are accessible +- Reports broken links +- Prevents dead links in documentation + +## Repository Automation + +### ๐Ÿท๏ธ [labeler.yml](workflows/labeler.yml) +**Purpose:** Auto-label PRs based on files changed +**Triggers:** Pull Requests (opened, synchronized, reopened) +**What it does:** +- Adds labels like `๐Ÿ“ฆ dependencies`, `๐Ÿ—๏ธ foundation`, `๐Ÿ”Œ drivers` +- Based on file paths changed +- Helps with PR organization and filtering + +### ๐Ÿ“ [pr-size-labeler.yml](workflows/pr-size-labeler.yml) โœจ NEW +**Purpose:** Label PRs by size +**Triggers:** Pull Requests (opened, synchronized, reopened) +**What it does:** +- Adds size labels: `size/XS`, `size/S`, `size/M`, `size/L`, `size/XL` +- XS: โ‰ค10 lines, S: โ‰ค50, M: โ‰ค200, L: โ‰ค500, XL: >500 +- Ignores lock files and markdown +- Encourages smaller, reviewable PRs + +### ๐Ÿ‘‹ [welcome.yml](workflows/welcome.yml) โœจ NEW +**Purpose:** Welcome first-time contributors +**Triggers:** First issue or PR from a new contributor +**What it does:** +- Posts welcoming message on first issue +- Provides PR checklist for first-time contributors +- Links to documentation and guidelines + +### ๐Ÿ—‘๏ธ [stale.yml](workflows/stale.yml) +**Purpose:** Manage stale issues and PRs +**Triggers:** Daily schedule, Manual dispatch +**What it does:** +- **Issues:** Mark stale after 60 days, close after 14 more days +- **PRs:** Mark stale after 30 days, close after 7 more days +- Exempts labeled issues: `pinned`, `security`, `roadmap` +- Helps keep issue tracker organized + +### ๐Ÿงน [cleanup-runs.yml](workflows/cleanup-runs.yml) โœจ NEW +**Purpose:** Clean up old workflow runs +**Triggers:** Weekly schedule (Sunday), Manual dispatch +**What it does:** +- Deletes workflow runs older than 30 days +- Keeps minimum of 6 recent runs +- Saves storage space +- Reduces clutter + +## Dependency Management + +### ๐Ÿค– [auto-approve-dependabot.yml](workflows/auto-approve-dependabot.yml) โœจ NEW +**Purpose:** Streamline Dependabot PR approvals +**Triggers:** Dependabot Pull Requests +**What it does:** +- Auto-approves patch and minor version updates +- Comments on major version updates for review +- Speeds up dependency update process +- Still requires CI to pass before merge + +## Performance Testing + +### โšก [benchmark.yml](workflows/benchmark.yml) โœจ NEW +**Purpose:** Track performance benchmarks +**Triggers:** Push to `main`, Pull Requests, Manual +**What it does:** +- Runs benchmark scripts (if configured) +- Tracks performance over time +- Alerts on significant regressions +- Ready for when benchmarks are implemented + +--- + +## Configuration Files + +### [labeler.yml](labeler.yml) +Configuration for the PR auto-labeler, mapping file paths to labels. + +### [markdown-link-check-config.json](markdown-link-check-config.json) โœจ NEW +Configuration for the link checker, including patterns to ignore (localhost, example.com). + +--- + +## Required Secrets + +The following secrets need to be configured in repository settings: + +- `NPM_TOKEN` - For publishing packages to npm (required by release.yml) +- `CODECOV_TOKEN` - For uploading coverage reports (optional for coverage.yml) + +--- + +## Workflow Status Badges + +Add these badges to your README to show workflow status: + +```markdown +[![CI](https://github.com/objectstack-ai/objectql/actions/workflows/ci.yml/badge.svg)](https://github.com/objectstack-ai/objectql/actions/workflows/ci.yml) +[![Coverage](https://codecov.io/gh/objectstack-ai/objectql/branch/main/graph/badge.svg)](https://codecov.io/gh/objectstack-ai/objectql) +[![Type Check](https://github.com/objectstack-ai/objectql/actions/workflows/typecheck.yml/badge.svg)](https://github.com/objectstack-ai/objectql/actions/workflows/typecheck.yml) +[![CodeQL](https://github.com/objectstack-ai/objectql/actions/workflows/codeql.yml/badge.svg)](https://github.com/objectstack-ai/objectql/actions/workflows/codeql.yml) +``` + +--- + +## Contributing + +When contributing to ObjectQL: + +1. **Write tests** - The CI workflow will run them +2. **Add a changeset** - Use `pnpm changeset` for user-facing changes +3. **Check types** - Run `pnpm tsc -b` locally +4. **Update docs** - If you change APIs or add features + +The workflows will automatically: +- Run tests and type checks +- Label your PR by size and files changed +- Welcome you if it's your first contribution +- Preview the changelog +- Check for broken links in docs + +--- + +**Legend:** +- โœจ NEW = Recently added workflows +- All workflows include proper timeouts and error handling +- All workflows are optimized for fast feedback diff --git a/.github/WORKFLOW_ENHANCEMENTS.md b/.github/WORKFLOW_ENHANCEMENTS.md new file mode 100644 index 00000000..e3795b3c --- /dev/null +++ b/.github/WORKFLOW_ENHANCEMENTS.md @@ -0,0 +1,84 @@ +# Workflow Enhancement Opportunities + +This document tracks potential future improvements for GitHub workflows. + +## Low Priority Enhancements + +### 1. Replace Third-Party Actions with GitHub Script + +Some workflows currently use third-party actions that could be replaced with `actions/github-script@v7` for improved security and reduced external dependencies: + +#### pr-size-labeler.yml +- **Current:** Uses `codelytv/pr-size-labeler@v1` +- **Status:** CodelyTV is a reputable organization, action works well +- **Future:** Could implement with github-script (~50 lines) +- **Benefit:** One less external dependency +- **Priority:** Low (current solution is secure and well-maintained) + +#### changelog-preview.yml +- **Current:** Uses `thollander/actions-comment-pull-request@v2` +- **Status:** Popular action, widely used in ecosystem +- **Future:** Could use github-script for commenting +- **Benefit:** One less external dependency +- **Priority:** Low (current solution is simple and reliable) + +#### benchmark.yml +- **Current:** Uses `benchmark-action/github-action-benchmark@v1` +- **Status:** Specialized benchmark tool with historical tracking +- **Future:** Custom implementation would be complex (100+ lines) +- **Benefit:** Full control over benchmark storage/comparison +- **Priority:** Very Low (current solution provides features that would be hard to replicate) + +### 2. Coverage Integration Enhancements + +- **Current:** Basic Codecov integration +- **Future Options:** + - Add coverage badges to README + - Set minimum coverage thresholds + - Block PRs that decrease coverage + - Generate coverage reports as PR comments + +### 3. Benchmark Integration + +- **Current:** Infrastructure ready but no benchmarks implemented +- **Future:** + - Add benchmark scripts to key packages + - Define performance budgets + - Alert on regressions + +### 4. Advanced PR Automation + +- **Future Ideas:** + - Auto-assign reviewers based on files changed + - Auto-label based on commit message keywords + - Integration with project boards + - Automatic milestone assignment + +## Security Considerations + +All current third-party actions: +- โœ… Are from reputable sources +- โœ… Have limited permissions +- โœ… Handle non-sensitive operations +- โœ… Don't have write access to code +- โœ… Are properly scoped with explicit permissions + +## Maintenance Notes + +- Review third-party action versions quarterly +- Monitor for security advisories +- Consider migration to github-script if: + - Action becomes unmaintained + - Security vulnerability is discovered + - Significant breaking changes occur + +## Implementation Priority + +1. **High:** None currently +2. **Medium:** Coverage enhancements, Benchmark implementation +3. **Low:** Replace third-party actions with github-script + +--- + +*Last Updated: 2026-01-15* +*Next Review: 2026-04-15* diff --git a/.github/markdown-link-check-config.json b/.github/markdown-link-check-config.json new file mode 100644 index 00000000..6d30f413 --- /dev/null +++ b/.github/markdown-link-check-config.json @@ -0,0 +1,66 @@ +{ + "ignorePatterns": [ + { + "pattern": "^http://localhost" + }, + { + "pattern": "^https://localhost" + }, + { + "pattern": "^http://127.0.0.1" + }, + { + "pattern": "^https://example.com" + }, + { + "pattern": "^https://www.google.com/search" + }, + { + "pattern": "^https://objectql.org" + }, + { + "pattern": "^https://www.objectql.org" + }, + { + "pattern": "^https://www.npmjs.com/package/@objectql/" + }, + { + "pattern": "^https://github.com/.*/releases/tag/.*%40" + }, + { + "pattern": "^mailto:" + }, + { + "pattern": "^https://img.shields.io/" + }, + { + "pattern": "^https://www.typescriptlang.org" + }, + { + "pattern": "^https://badge.fury.io/" + }, + { + "pattern": "^https://unpkg.com/" + }, + { + "pattern": "^https://cdn.jsdelivr.net/" + }, + { + "pattern": "^https://discord.gg/" + } + ], + "replacementPatterns": [], + "httpHeaders": [ + { + "urls": ["https://github.com"], + "headers": { + "Accept-Encoding": "zstd, br, gzip, deflate" + } + } + ], + "timeout": "20s", + "retryOn429": true, + "retryCount": 3, + "fallbackRetryDelay": "30s", + "aliveStatusCodes": [200, 206] +} diff --git a/.github/workflows/auto-approve-dependabot.yml b/.github/workflows/auto-approve-dependabot.yml new file mode 100644 index 00000000..aceec4f7 --- /dev/null +++ b/.github/workflows/auto-approve-dependabot.yml @@ -0,0 +1,36 @@ +name: "Auto-approve Dependabot PRs" + +on: + pull_request_target: + types: [opened, synchronize, reopened] + +permissions: + pull-requests: write + contents: write + +jobs: + auto-approve: + runs-on: ubuntu-latest + timeout-minutes: 3 + if: github.actor == 'dependabot[bot]' + steps: + - name: Dependabot metadata + id: metadata + uses: dependabot/fetch-metadata@v2 + with: + github-token: "${{ secrets.GITHUB_TOKEN }}" + + - name: Auto-approve patch and minor updates + if: (steps.metadata.outputs.update-type == 'version-update:semver-patch') || (steps.metadata.outputs.update-type == 'version-update:semver-minor') + run: gh pr review --approve "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Comment on major updates + if: steps.metadata.outputs.update-type == 'version-update:semver-major' + run: | + gh pr comment "$PR_URL" --body "โš ๏ธ This is a **major version update**. Please review the changelog carefully before merging." + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml new file mode 100644 index 00000000..cf8bb73b --- /dev/null +++ b/.github/workflows/benchmark.yml @@ -0,0 +1,82 @@ +name: "Performance Benchmark" + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + workflow_dispatch: + +permissions: + contents: write + pull-requests: write + +jobs: + benchmark: + name: Run Performance Benchmarks + runs-on: ubuntu-latest + timeout-minutes: 10 + services: + redis: + image: redis + ports: + - 6379:6379 + options: >- + --health-cmd "redis-cli ping" + --health-interval 10s + --health-timeout 5s + --health-retries 5 + + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v3 + with: + version: 10 + + - name: Use Node.js 20.x + uses: actions/setup-node@v4 + with: + node-version: 20.x + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install --frozen-lockfile + timeout-minutes: 2 + + - name: Build packages + run: pnpm run build + timeout-minutes: 3 + + - name: Run benchmarks + id: run-benchmarks + run: | + echo "Checking for benchmark scripts..." + if pnpm -r list | grep -q "benchmark"; then + echo "Running benchmarks..." + pnpm -r run benchmark --if-present + if [ -f "benchmark-results.json" ]; then + echo "benchmark_file_exists=true" >> $GITHUB_OUTPUT + else + echo "benchmark_file_exists=false" >> $GITHUB_OUTPUT + fi + else + echo "No benchmark scripts found. Skipping benchmarks." + echo "To add benchmarks, add a 'benchmark' script to package.json files." + echo "benchmark_file_exists=false" >> $GITHUB_OUTPUT + fi + timeout-minutes: 5 + continue-on-error: true + + - name: Store benchmark result + if: github.ref == 'refs/heads/main' && steps.run-benchmarks.outputs.benchmark_file_exists == 'true' + uses: benchmark-action/github-action-benchmark@v1 + with: + name: ObjectQL Benchmarks + tool: 'benchmarkjs' + output-file-path: benchmark-results.json + github-token: ${{ secrets.GITHUB_TOKEN }} + auto-push: true + comment-on-alert: true + alert-threshold: '150%' + fail-on-alert: false diff --git a/.github/workflows/changelog-preview.yml b/.github/workflows/changelog-preview.yml new file mode 100644 index 00000000..7a2ee153 --- /dev/null +++ b/.github/workflows/changelog-preview.yml @@ -0,0 +1,60 @@ +name: "Changelog Preview" + +on: + pull_request: + types: [opened, synchronize, labeled, unlabeled] + +permissions: + contents: read + pull-requests: write + +jobs: + changelog-preview: + name: Generate Changelog Preview + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: pnpm/action-setup@v3 + with: + version: 10 + + - name: Use Node.js 20.x + uses: actions/setup-node@v4 + with: + node-version: 20.x + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install --frozen-lockfile + timeout-minutes: 2 + + - name: Generate Changeset Preview + run: | + echo "Checking for changeset files..." + if [ -d ".changeset" ] && [ "$(ls -A .changeset/*.md 2>/dev/null | grep -v README | wc -l)" -gt 0 ]; then + echo "### ๐Ÿ“‹ Changelog Preview" > changeset-preview.md + echo "" >> changeset-preview.md + echo "The following changes will be included in the next release:" >> changeset-preview.md + echo "" >> changeset-preview.md + pnpm changeset status --verbose >> changeset-preview.md 2>&1 || echo "Changeset status completed with warnings" + else + echo "### โš ๏ธ No Changeset Found" > changeset-preview.md + echo "" >> changeset-preview.md + echo "This PR does not include a changeset file." >> changeset-preview.md + echo "If this PR includes user-facing changes, please add a changeset by running:" >> changeset-preview.md + echo "\`\`\`bash" >> changeset-preview.md + echo "pnpm changeset" >> changeset-preview.md + echo "\`\`\`" >> changeset-preview.md + fi + timeout-minutes: 1 + + - name: Comment Changeset Preview + uses: thollander/actions-comment-pull-request@v2 + with: + filePath: changeset-preview.md + comment-tag: changeset-preview diff --git a/.github/workflows/cleanup-runs.yml b/.github/workflows/cleanup-runs.yml new file mode 100644 index 00000000..a688c827 --- /dev/null +++ b/.github/workflows/cleanup-runs.yml @@ -0,0 +1,74 @@ +name: "Delete Old Workflow Runs" + +on: + schedule: + # Run every week on Sunday at 00:00 UTC + - cron: '0 0 * * 0' + workflow_dispatch: + +permissions: + actions: write + contents: read + +jobs: + delete-old-runs: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Delete workflow runs older than 30 days + uses: actions/github-script@v7 + with: + script: | + const days_to_keep = 30; + const minimum_runs_to_keep = 6; + const cutoff_date = new Date(Date.now() - (days_to_keep * 24 * 60 * 60 * 1000)); + + const workflows = await github.rest.actions.listRepoWorkflows({ + owner: context.repo.owner, + repo: context.repo.repo + }); + + for (const workflow of workflows.data.workflows) { + console.log(`Processing workflow: ${workflow.name} (${workflow.id})`); + + const runs = await github.rest.actions.listWorkflowRuns({ + owner: context.repo.owner, + repo: context.repo.repo, + workflow_id: workflow.id, + per_page: 100 + }); + + // Sort runs by created date, newest first + const sortedRuns = runs.data.workflow_runs.sort((a, b) => + new Date(b.created_at) - new Date(a.created_at) + ); + + // Keep the most recent runs and delete older ones + for (let i = 0; i < sortedRuns.length; i++) { + const run = sortedRuns[i]; + const run_date = new Date(run.created_at); + + // Keep minimum number of recent runs + if (i < minimum_runs_to_keep) { + console.log(`Keeping recent run #${run.id} (${run.name})`); + continue; + } + + // Delete runs older than cutoff date + if (run_date < cutoff_date) { + console.log(`Deleting old run #${run.id} from ${run.created_at}`); + try { + await github.rest.actions.deleteWorkflowRun({ + owner: context.repo.owner, + repo: context.repo.repo, + run_id: run.id + }); + } catch (error) { + console.log(`Failed to delete run #${run.id}: ${error.message}`); + } + } + } + } + + console.log('Cleanup complete!'); + diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml new file mode 100644 index 00000000..2ccfe86e --- /dev/null +++ b/.github/workflows/coverage.yml @@ -0,0 +1,79 @@ +name: Test Coverage + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + +permissions: + contents: read + pull-requests: write + +jobs: + coverage: + name: Test Coverage Report + runs-on: ubuntu-latest + timeout-minutes: 8 + services: + redis: + image: redis + ports: + - 6379:6379 + options: >- + --health-cmd "redis-cli ping" + --health-interval 10s + --health-timeout 5s + --health-retries 5 + + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v3 + with: + version: 10 + + - name: Use Node.js 20.x + uses: actions/setup-node@v4 + with: + node-version: 20.x + cache: 'pnpm' + + - name: Cache MongoDB Binary + uses: actions/cache@v4 + with: + path: ~/.cache/mongodb-binaries + key: mongodb-binaries-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }} + restore-keys: | + mongodb-binaries-${{ runner.os }}- + + - name: Install dependencies + run: pnpm install --frozen-lockfile + timeout-minutes: 2 + + - name: Setup MongoDB Memory Server + run: | + # Pre-download MongoDB binary for mongodb-memory-server + cd packages/drivers/mongo + npx mongodb-memory-server preinstall || echo "MongoDB binary download failed, tests will skip gracefully" + timeout-minutes: 1 + continue-on-error: true + + - name: Build packages + run: pnpm run build + timeout-minutes: 3 + + - name: Run tests with coverage + run: pnpm -r run test -- --coverage --coverageReporters=text --coverageReporters=lcov + timeout-minutes: 5 + continue-on-error: true + + - name: Upload coverage reports to Codecov + uses: codecov/codecov-action@v4 + with: + token: ${{ secrets.CODECOV_TOKEN }} + files: ./packages/*/coverage/lcov.info + flags: unittests + name: codecov-umbrella + fail_ci_if_error: false + verbose: true diff --git a/.github/workflows/link-checker.yml b/.github/workflows/link-checker.yml new file mode 100644 index 00000000..22298463 --- /dev/null +++ b/.github/workflows/link-checker.yml @@ -0,0 +1,39 @@ +name: "Check Documentation Links" + +on: + # push: + # branches: [ "main" ] + # paths: + # - 'docs/**' + # - '**/*.md' + # pull_request: + # branches: [ "main" ] + # paths: + # - 'docs/**' + # - '**/*.md' + # schedule: + # # Run weekly on Monday at 00:00 UTC + # - cron: '0 0 * * 1' + workflow_dispatch: + +permissions: + contents: read + issues: write + +jobs: + link-checker: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + + - name: Check Links in Markdown Files + uses: gaurav-nelson/github-action-markdown-link-check@v1 + with: + use-quiet-mode: 'yes' + use-verbose-mode: 'no' + config-file: '.github/markdown-link-check-config.json' + folder-path: '.' + max-depth: -1 + check-modified-files-only: 'no' diff --git a/.github/workflows/pr-size-labeler.yml b/.github/workflows/pr-size-labeler.yml new file mode 100644 index 00000000..d94f7721 --- /dev/null +++ b/.github/workflows/pr-size-labeler.yml @@ -0,0 +1,37 @@ +name: "PR Size Labeler" + +on: + pull_request: + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + +jobs: + size-label: + runs-on: ubuntu-latest + timeout-minutes: 3 + steps: + - name: Label PR by Size + uses: codelytv/pr-size-labeler@v1 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + xs_label: 'size/XS' + xs_max_size: 10 + s_label: 'size/S' + s_max_size: 50 + m_label: 'size/M' + m_max_size: 200 + l_label: 'size/L' + l_max_size: 500 + xl_label: 'size/XL' + fail_if_xl: false + message_if_xl: > + This PR is very large. Consider splitting it into smaller PRs for easier review. + files_to_ignore: | + pnpm-lock.yaml + package-lock.json + yarn.lock + *.md + *.txt diff --git a/.github/workflows/welcome.yml b/.github/workflows/welcome.yml new file mode 100644 index 00000000..fdd95699 --- /dev/null +++ b/.github/workflows/welcome.yml @@ -0,0 +1,45 @@ +name: "Welcome First-Time Contributors" + +on: + issues: + types: [opened] + pull_request_target: + types: [opened] + +permissions: + issues: write + pull-requests: write + +jobs: + welcome: + runs-on: ubuntu-latest + timeout-minutes: 3 + steps: + - name: Welcome First-Time Contributors + uses: actions/first-interaction@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + issue-message: | + ๐Ÿ‘‹ Welcome to ObjectQL! + + Thank you for opening your first issue. We appreciate your contribution to the project! + + Our team will review your issue and get back to you as soon as possible. In the meantime: + - Make sure you've provided all relevant details + - Check our [documentation](https://github.com/objectstack-ai/objectql/tree/main/docs) if you haven't already + - Feel free to ask questions if you need clarification + + Happy coding! ๐Ÿš€ + pr-message: | + ๐Ÿ‘‹ Welcome to ObjectQL! + + Thank you for submitting your first pull request! We're excited to review your contribution. + + Before we proceed, please ensure: + - [ ] Your code follows our coding standards + - [ ] All tests pass (`pnpm test`) + - [ ] TypeScript compilation succeeds (`pnpm tsc -b`) + - [ ] You've added tests for new functionality (if applicable) + - [ ] You've updated documentation (if applicable) + + Our maintainers will review your PR soon. Thank you for contributing to ObjectQL! ๐ŸŽ‰ diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 3e718fa2..3af29208 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -38,7 +38,7 @@ This unifies the previous concepts of `source`, `dir` and `presets`. ### `plugins` ((ObjectQLPlugin | string)[]) A list of plugin instances OR package names to extend the core functionality. -See [Plugin System](./plugins.html) for details. +See [Plugin System](./plugins.md) for details. ### `objects` (Record) (Advanced) In-memory definition of objects. Useful for dynamic runtime schema generation. diff --git a/docs/guide/drivers/extensibility.md b/docs/guide/drivers/extensibility.md index 0be72d14..fb9ba69f 100644 --- a/docs/guide/drivers/extensibility.md +++ b/docs/guide/drivers/extensibility.md @@ -147,7 +147,7 @@ To implement a custom driver: - [`@objectql/driver-sql`](../../../packages/drivers/sql/src/index.ts) - SQL databases - [`@objectql/driver-mongo`](../../../packages/drivers/mongo/src/index.ts) - MongoDB 3. Review the [Driver Interface](../../../packages/foundation/types/src/driver.ts) -4. Follow the [Driver Testing Guide](./testing-drivers.md) (coming soon) +4. Follow the driver testing patterns from existing drivers (see the test suites in `@objectql/driver-sql` and `@objectql/driver-mongo`) ## Community Drivers diff --git a/docs/guide/drivers/index.md b/docs/guide/drivers/index.md index 3c0c430a..422be13f 100644 --- a/docs/guide/drivers/index.md +++ b/docs/guide/drivers/index.md @@ -8,15 +8,15 @@ You can configure multiple drivers for different parts of your application, or u We currently support the following official drivers: -* **[SQL Driver](./sql)**: Supports PostgreSQL, MySQL, SQLite, MSSQL, etc. -* **[MongoDB Driver](./mongo)**: Supports MongoDB. +* **[SQL Driver](./sql.md)**: Supports PostgreSQL, MySQL, SQLite, MSSQL, etc. +* **[MongoDB Driver](./mongo.md)**: Supports MongoDB. ## Extensibility ObjectQL is designed to support additional database types through custom drivers. -* **[Driver Extensibility Guide](./extensibility)**: Learn about potential database types that can be supported and how to choose the right one for your needs. -* **[Implementing a Custom Driver](./implementing-custom-driver)**: Step-by-step guide to building your own database driver for ObjectQL. +* **[Driver Extensibility Guide](./extensibility.md)**: Learn about potential database types that can be supported and how to choose the right one for your needs. +* **[Implementing a Custom Driver](./implementing-custom-driver.md)**: Step-by-step guide to building your own database driver for ObjectQL. ## Unified ID Field diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 93cceb6a..3feddd08 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -200,5 +200,5 @@ await ctx.object('todo').execute('mark_done', 'id_123', {}); * **[Database Drivers](./drivers/index.md)**: Connect to PostgreSQL, MongoDB, etc. * **[Data Modeling](./data-modeling.md)**: Learn about all field types (Select, Lookup, Date, etc.) -* **[SDK Reference](./sdk-reference.md)**: Explore the full API. +* **[API Reference](../api/index.md)**: Explore the full API. * **[Hooks](./logic-hooks.md)**: Deep dive into the event system. diff --git a/docs/guide/ide-setup.md b/docs/guide/ide-setup.md index 5f02c2ee..ed7a0a1d 100644 --- a/docs/guide/ide-setup.md +++ b/docs/guide/ide-setup.md @@ -107,4 +107,4 @@ ObjectQL is designed to be "AI-Native". The most efficient way to write schema a We strongly recommend configuring your AI Coding Assistant (GitHub Copilot, Cursor, Windsurf) with our specialized System Prompts. These prompts teach the AI about ObjectQL's metadata protocol. -[๐Ÿ‘‰ Go to AI Coding Assistant Guide](/ai/coding-assistant) +[๐Ÿ‘‰ Go to AI Coding Assistant Guide](../ai/coding-assistant.md) diff --git a/docs/guide/index.md b/docs/guide/index.md index 351f39d0..91e5d110 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -56,14 +56,14 @@ Your application logic isn't hidden inside controller functions. It's attached t ObjectQL exposes your data through multiple API styles: -* **[Complete API Reference](../api/README.md)** - Comprehensive guide to all endpoints -* **[JSON-RPC API](../api/README.md#json-rpc-style-api)** - Universal protocol for all operations -* **[REST API](../api/README.md#rest-style-api)** - Traditional REST endpoints -* **[Metadata API](../api/README.md#metadata-api)** - Runtime schema discovery +* **[Complete API Reference](../api/index.md)** - Comprehensive guide to all endpoints +* **[JSON-RPC API](../api/json-rpc.md)** - Universal protocol for all operations +* **[REST API](../api/rest.md)** - Traditional REST endpoints +* **[Metadata API](../api/metadata.md)** - Runtime schema discovery * **[Authentication Guide](../api/authentication.md)** - Securing your APIs ## Next Steps * [**Getting Started**](./getting-started.md): Build your first ObjectQL app * [**CLI Tool**](./cli.md): Using the command line interface for codegen -* [**API Reference**](../api/README.md): Complete API documentation +* [**API Reference**](../api/index.md): Complete API documentation diff --git a/docs/guide/metadata-organization.md b/docs/guide/metadata-organization.md index 299bd2e4..c7a53a97 100644 --- a/docs/guide/metadata-organization.md +++ b/docs/guide/metadata-organization.md @@ -362,4 +362,4 @@ The example includes: - [Data Modeling Guide](./data-modeling.md) - [Plugin Development](./plugins.md) - [Logic Hooks](./logic-hooks.md) -- [Complete Example](../../packages/starters/enterprise/) +- See examples in the repository under `examples/` directory diff --git a/docs/guide/migration-id-field.md b/docs/guide/migration-id-field.md index a0b58785..e0378d7f 100644 --- a/docs/guide/migration-id-field.md +++ b/docs/guide/migration-id-field.md @@ -277,7 +277,7 @@ ALTER TABLE users_new RENAME TO users; If you encounter issues during migration: 1. Check the [Driver Documentation](./drivers/index.md) -2. Review the [API Reference](../api/README.md) +2. Review the [API Reference](../api/index.md) 3. Open an issue on [GitHub](https://github.com/objectql/objectql/issues) ## Summary diff --git a/docs/guide/query-best-practices.md b/docs/guide/query-best-practices.md index 22ef87f7..3b57cfbd 100644 --- a/docs/guide/query-best-practices.md +++ b/docs/guide/query-best-practices.md @@ -820,6 +820,6 @@ query { **Need Help?** -- ๐Ÿ“– [Documentation](https://objectql.org/docs) +- ๐Ÿ“– [Documentation](../index.md) - ๐Ÿ’ฌ [Community Discord](https://discord.gg/objectql) - ๐Ÿ› [Report Issues](https://github.com/objectstack-ai/objectql/issues) diff --git a/docs/guide/server-integration.md b/docs/guide/server-integration.md index 70c80ee4..c017eeba 100644 --- a/docs/guide/server-integration.md +++ b/docs/guide/server-integration.md @@ -112,4 +112,4 @@ For rapid prototyping, `@objectql/cli` provides a built-in dev server. objectql serve ``` -See [CLI Documentation](../package/cli) for more details. +See [CLI Documentation](./cli.md) for more details. diff --git a/docs/index.md b/docs/index.md index ecd11f1a..de3477a1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -116,7 +116,7 @@ ObjectQL abstracts the entire backend into a **Standardized Protocol**: ## Next Steps -* **[๐Ÿค– Configure your AI Assistant](/ai/coding-assistant)**: Get the System Prompts to turn Cursor/Copilot into an ObjectQL expert. -* **[๐Ÿš€ Start a Tutorial](/tutorials/)**: Build a Task Manager or CRM in minutes to understand the flow. -* **[๐Ÿ”Œ Building AI Agents](/ai/building-apps)**: Learn how to use ObjectQL as the tool interface for autonomous agents. -* **[๐Ÿ“š Developer Guide](/guide/getting-started)**: The classic manual for human developers. +* **[๐Ÿค– Configure your AI Assistant](./ai/coding-assistant.md)**: Get the System Prompts to turn Cursor/Copilot into an ObjectQL expert. +* **[๐Ÿš€ Start a Tutorial](./tutorials/index.md)**: Build a Task Manager or CRM in minutes to understand the flow. +* **[๐Ÿ”Œ Building AI Agents](./ai/building-apps.md)**: Learn how to use ObjectQL as the tool interface for autonomous agents. +* **[๐Ÿ“š Developer Guide](./guide/getting-started.md)**: The classic manual for human developers. diff --git a/docs/tutorials/ai-agent.md b/docs/tutorials/ai-agent.md index 334645df..6d404043 100644 --- a/docs/tutorials/ai-agent.md +++ b/docs/tutorials/ai-agent.md @@ -1,6 +1,6 @@ # Building an Autonomous Data Agent -> **Prerequisites**: [Task Manager Tutorial](./task-manager). +> **Prerequisites**: [Task Manager Tutorial](./task-manager.md). > **Concepts**: ObjectQL as a "Tool" for LLMs. In this tutorial, we will build an AI Agent that can answer questions about your data by autonomously querying the ObjectQL database. We will use OpenAI's "Function Calling" capability. diff --git a/docs/tutorials/crm-system.md b/docs/tutorials/crm-system.md index 40230207..5626b215 100644 --- a/docs/tutorials/crm-system.md +++ b/docs/tutorials/crm-system.md @@ -1,6 +1,6 @@ # Building a Micro-CRMSystem -> **Prerequisites**: Completed [Build Your First App](./task-manager). +> **Prerequisites**: Completed [Build Your First App](./task-manager.md). In this tutorial, we will explore **Relationships**, **Validation**, and **Hooks** by building a minimal CRM (Customer Relationship Management) system. diff --git a/docs/tutorials/federation.md b/docs/tutorials/federation.md index d6eefc84..b64281ed 100644 --- a/docs/tutorials/federation.md +++ b/docs/tutorials/federation.md @@ -1,6 +1,6 @@ # Federated Data Graph -> **Prerequisites**: [Building a Micro-CRM](./crm-system). +> **Prerequisites**: [Building a Micro-CRM](./crm-system.md). > **Requirements**: A running MongoDB instance (or use a cloud provider URI). In this advanced tutorial, we will demonstrate **Data Federation**. We will connect to two different databases simultaneously: diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 9cc20ea9..f52454c4 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -4,7 +4,7 @@ Welcome to the ObjectQL learning path. These tutorials are designed to take you ## ๐Ÿ‘ถ Beginner -### [Build Your First App: Task Manager](./task-manager) +### [Build Your First App: Task Manager](./task-manager.md) **Time**: 15 mins **Goal**: Create a simple schema, run the server, and manage data via the Studio. - Define `Task` object @@ -13,7 +13,7 @@ Welcome to the ObjectQL learning path. These tutorials are designed to take you ## ๐Ÿง‘โ€๐Ÿ’ป Intermediate -### [Building a Micro-CRM](./crm-system) +### [Building a Micro-CRM](./crm-system.md) **Time**: 30 mins **Goal**: Learn relationships, permissions, and business logic. - Define `Account` and `Contact` with 1:N relationships @@ -22,7 +22,7 @@ Welcome to the ObjectQL learning path. These tutorials are designed to take you ## ๐Ÿ— Advanced -### [Federated Data Graph](./federation) +### [Federated Data Graph](./federation.md) **Time**: 45 mins **Goal**: Connect multiple databases into one graph. - Setup Mongo for `Logs` diff --git a/packages/drivers/excel/EXAMPLE.md b/packages/drivers/excel/EXAMPLE.md index 078bd857..83251bc0 100644 --- a/packages/drivers/excel/EXAMPLE.md +++ b/packages/drivers/excel/EXAMPLE.md @@ -193,6 +193,6 @@ The Excel file will look like this: ## Next Steps -- Explore the [full API documentation](../README.md) -- Check out other drivers: [SQL](../../sql), [MongoDB](../../mongo), [Memory](../../memory) +- Explore the [full API documentation](./README.md) +- Check out other drivers: [SQL](../sql), [MongoDB](../mongo), [Memory](../memory) - Learn about [ObjectQL](../../../README.md) diff --git a/packages/drivers/excel/README.md b/packages/drivers/excel/README.md index 4dcde8ed..8689a806 100644 --- a/packages/drivers/excel/README.md +++ b/packages/drivers/excel/README.md @@ -630,15 +630,15 @@ MIT ## ๐Ÿ”— Related Packages -- [@objectql/types](../foundation/types) - Core ObjectQL types -- [@objectql/core](../foundation/core) - ObjectQL core engine +- [@objectql/types](../../foundation/types) - Core ObjectQL types +- [@objectql/core](../../foundation/core) - ObjectQL core engine - [@objectql/driver-memory](../memory) - In-memory driver - [@objectql/driver-sql](../sql) - SQL database driver - [@objectql/driver-mongo](../mongo) - MongoDB driver ## ๐Ÿ™ Contributing -Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details. +Contributions are welcome! Please see the repository's issue tracker and pull request guidelines. ## ๐Ÿ› Issues diff --git a/packages/drivers/memory/README.md b/packages/drivers/memory/README.md index 3b2b5fb2..9f6ca786 100644 --- a/packages/drivers/memory/README.md +++ b/packages/drivers/memory/README.md @@ -145,7 +145,7 @@ The Memory Driver works seamlessly in web browsers! Perfect for prototyping, cli ### Interactive Browser Demo -See the **[Browser Demo](../../../examples/browser-demo/)** for a complete interactive example with: +See the **examples** in the repository for interactive demonstrations. - ๐ŸŽจ Beautiful UI with live CRUD operations - ๐Ÿ–ฅ๏ธ Browser console debugging - ๐Ÿ“Š Real-time statistics diff --git a/packages/drivers/sdk/README.md b/packages/drivers/sdk/README.md index 5ae2f1ed..df2a182a 100644 --- a/packages/drivers/sdk/README.md +++ b/packages/drivers/sdk/README.md @@ -2,7 +2,7 @@ > **Remote HTTP Driver for ObjectQL** - Universal client for browser, Node.js, and edge runtimes -[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../../LICENSE) [![TypeScript](https://img.shields.io/badge/written%20in-TypeScript-3178C6.svg)](https://www.typescriptlang.org/) The `@objectql/sdk` package provides a type-safe HTTP client for ObjectQL servers. It works seamlessly in browsers, Node.js, Deno, and edge runtimes like Cloudflare Workers. @@ -473,7 +473,7 @@ The SDK is designed with the ObjectQL "Trinity" architecture: ## ๐Ÿ“„ License -MIT License - see [LICENSE](../../LICENSE) file for details. +MIT License - see [LICENSE](../../../LICENSE) file for details. --- @@ -496,4 +496,4 @@ We welcome contributions! Please see the main [repository README](../../../READM For complete documentation, visit: * [Client SDK Guide](../../../docs/api/client-sdk.md) * [REST API Reference](../../../docs/api/rest.md) -* [ObjectQL Documentation](https://objectql.org) +* [ObjectQL Documentation](https://github.com/objectstack-ai/objectql) diff --git a/packages/foundation/core/README.md b/packages/foundation/core/README.md index abd466c6..97276b1a 100644 --- a/packages/foundation/core/README.md +++ b/packages/foundation/core/README.md @@ -284,4 +284,4 @@ new Validator(options?: ValidatorOptions) ## See Also - [@objectql/types](../types) - Type definitions including validation types -- [Validation Specification](../../docs/spec/validation.md) - Complete validation metadata specification +- [Validation Specification](../../../docs/spec/validation.md) - Complete validation metadata specification diff --git a/packages/foundation/types/README.md b/packages/foundation/types/README.md index 49fd3d8c..46946188 100644 --- a/packages/foundation/types/README.md +++ b/packages/foundation/types/README.md @@ -389,5 +389,5 @@ const deleteObject: ObjectDeleteInstruction = { ## See Also - [@objectql/core](../core) - Core engine with Validator class -- [Validation Specification](../../docs/spec/validation.md) - Complete validation metadata specification +- [Validation Specification](../../../docs/spec/validation.md) - Complete validation metadata specification diff --git a/packages/runtime/server/src/adapters/rest.ts b/packages/runtime/server/src/adapters/rest.ts index b2922831..7c4c65d6 100644 --- a/packages/runtime/server/src/adapters/rest.ts +++ b/packages/runtime/server/src/adapters/rest.ts @@ -273,6 +273,16 @@ export function createRESTHandler(app: IObjectQL, options?: RESTHandlerOptions) // Execute the request const result = await server.handle(qlRequest); + if (!result) { + sendJSON(res, 404, { + error: { + code: ErrorCode.NOT_FOUND, + message: 'Resource not found' + } + }); + return; + } + // Determine HTTP status code let statusCode = 200; if (result.error) { diff --git a/packages/runtime/server/test/node.test.ts b/packages/runtime/server/test/node.test.ts index bf4c2c2f..7d22c8f0 100644 --- a/packages/runtime/server/test/node.test.ts +++ b/packages/runtime/server/test/node.test.ts @@ -84,11 +84,13 @@ describe('Node Adapter', () => { }); }); - it('should return 405 for GET', async () => { + it('should return 200 with welcome page for GET root', async () => { const handler = createNodeHandler(app); server = createServer(handler); const response = await request(server).get('/'); - expect(response.status).toBe(405); + expect(response.status).toBe(200); + expect(response.headers['content-type']).toContain('text/html'); + expect(response.text).toContain('ObjectQL Server'); }); }); diff --git a/packages/tools/vscode-objectql/README.md b/packages/tools/vscode-objectql/README.md index 8c95a6a8..e776e6c0 100644 --- a/packages/tools/vscode-objectql/README.md +++ b/packages/tools/vscode-objectql/README.md @@ -1,6 +1,6 @@ # ObjectQL - Visual Studio Code Extension -![ObjectQL Logo](images/icon.png) +![ObjectQL Logo](images/icon.svg) **The Standard Protocol for AI Software Generation** @@ -285,7 +285,7 @@ Contributions are welcome! Please see the main repository for contribution guide ## ๐Ÿ“„ License -MIT License - see [LICENSE](../../LICENSE) for details. +MIT License - see [LICENSE](../../../LICENSE) for details. --- diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 58c10449..1822522a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -187,10 +187,10 @@ importers: devDependencies: '@types/node': specifier: ^20.11.24 - version: 20.19.28 + version: 20.19.29 ts-node: specifier: ^10.9.2 - version: 10.9.2(@types/node@20.19.28)(typescript@5.9.3) + version: 10.9.2(@types/node@20.19.29)(typescript@5.9.3) typescript: specifier: ^5.3.3 version: 5.9.3 @@ -533,7 +533,7 @@ importers: version: 11.0.4 '@types/node': specifier: ^20.0.0 - version: 20.19.28 + version: 20.19.29 typescript: specifier: ^5.0.0 version: 5.9.3 @@ -1892,9 +1892,6 @@ packages: '@types/node@18.19.130': resolution: {integrity: sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==} - '@types/node@20.19.28': - resolution: {integrity: sha512-VyKBr25BuFDzBFCK5sUM6ZXiWfqgCTwTAOK8qzGV/m9FCirXYDlmczJ+d5dXBAQALGCdRRdbteKYfJ84NGEusw==} - '@types/node@20.19.29': resolution: {integrity: sha512-YrT9ArrGaHForBaCNwFjoqJWmn8G1Pr7+BH/vwyLHciA9qT/wSiuOhxGCT50JA5xLvFBd6PIiGkE3afxcPE1nw==} @@ -7395,10 +7392,6 @@ snapshots: dependencies: undici-types: 5.26.5 - '@types/node@20.19.28': - dependencies: - undici-types: 6.21.0 - '@types/node@20.19.29': dependencies: undici-types: 6.21.0 @@ -11532,24 +11525,6 @@ snapshots: tslib: 2.8.1 typescript: 5.9.3 - ts-node@10.9.2(@types/node@20.19.28)(typescript@5.9.3): - dependencies: - '@cspotcode/source-map-support': 0.8.1 - '@tsconfig/node10': 1.0.12 - '@tsconfig/node12': 1.0.11 - '@tsconfig/node14': 1.0.3 - '@tsconfig/node16': 1.0.4 - '@types/node': 20.19.28 - acorn: 8.15.0 - acorn-walk: 8.3.4 - arg: 4.1.3 - create-require: 1.1.1 - diff: 4.0.2 - make-error: 1.3.6 - typescript: 5.9.3 - v8-compile-cache-lib: 3.0.1 - yn: 3.1.1 - ts-node@10.9.2(@types/node@20.19.29)(typescript@5.9.3): dependencies: '@cspotcode/source-map-support': 0.8.1