Development And Testing

This page is for contributors working on ../git-vibe. User setup lives in Quick Start.

Repository Shape

../git-vibe/
  src/
    app/
    runner/
    shared/
  prompts/
  schemas/stages/
  .github/workflows/
  examples/consumer/
  packages/git-vibe-setup/
  tests/

flowchart LR
  App[src/app] --> Tests[tests]
  Runner[src/runner] --> Tests
  Shared[src/shared] --> App
  Shared --> Runner
  Prompts[prompts] --> Runner
  Schemas[schemas/stages] --> Runner
  Workflows[.github/workflows] --> Actions[composite actions]

Local Setup

corepack pnpm install --frozen-lockfile

Node 22 and pnpm 10.33.3 are the expected versions. GitHub workflow steps use Node 24-backed action majors such as actions/setup-node@v6, actions/checkout@v7, actions/upload-artifact@v7, and pnpm/action-setup@v6, while the project runtime remains Node 22.

Quality Gates

Full gate:

corepack pnpm check

Individual commands:

corepack pnpm format:check
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm test
corepack pnpm coverage
corepack pnpm build
corepack pnpm actionlint
corepack pnpm audit --prod

Coverage thresholds:

branches: 90%
functions: 90%
lines: 90%
statements: 90%

ESLint size limits apply to JavaScript and MJS files:

max file length: 700 lines
max function length: 100 lines

Build Outputs

flowchart TD
  A[TypeScript source] --> B[corepack pnpm build]
  B --> C[dist/app and dist/shared]
  B --> D[dist/actions runner bundles]
  C --> E[Docker image]
  D --> F[Composite action execution]

dist/ is generated and ignored by git. The Docker image copies app/shared output. Composite actions build runner bundles before stage execution.

AI Smoke Tests

Use the AI smoke test workflow after runner/provider setup.

All smoke paths read GITVIBE_AI_ENV_JSON. Bundle details are in Secret Bundle Shape. Codex SDK and Claude Code SDK smoke tests run on Linux or macOS runners only. The workflow resolves the native Codex executable before Codex runs and fails if the SDK optional binary is unavailable. It resolves the SDK native Claude Code executable first and falls back to Anthropic's shell installer when no Claude executable is available.

Source Change Boundaries

Runner-only changes should not require app deployment unless they also touch shared code, app code, package metadata, Docker/deploy files, or deployment workflows.

Repository-local workflow notes:

• investigate.yml, validate.yml, materialize.yml, and review.yml are reusable workflows and also support workflow_dispatch for source-repo testing.
• automatic-pr-review.yml is the repository-local pull_request_target wrapper that reviews non-draft PRs opened against main or dev.
• ci.yml is the PR quality gate plus manual dispatch for format, lint, coverage, build, actionlint, and production audit.
• release.yml is the admin-only release workflow. Stable tags run from main; prerelease tags run from dev.
• The release workflow builds app images only when app-impacting paths changed. Runner-only releases skip app image build and deployment.
• app-deploy.yml deploys the semantic image tag produced by release workflow only for app-impacting prereleases.

Test Focus

The test suite covers:

• Command parsing.
• Config loading and AI profile routing.
• Webhook event handling.
• Label transitions and protected label behavior.
• Stage contracts and schema validation.
• Context assembly.
• Result comments and hidden markers.
• Materialized issue creation, PR review publishing, and approval tracking.
• SDK adapter setup and auth preflight.
• AI SDK logging, retries, and output validation.

Use focused tests for narrow changes and broaden tests when touching shared behavior, stage contracts, or GitHub write paths.