Writing the Verification Script

This document defines how to create ./scripts/verify.sh, the standardized entry point for project validation.

Overview

The verification script is a prerequisite for implementation planning. It provides a single command that runs all quality checks (tests, linting, formatting, type checking) regardless of the underlying toolchain.

./scripts/verify.sh
    ↓
[Project-specific tools: tests, linter, formatter, type checker]
    ↓
Exit 0 (success) or non-zero (failure)

Why a Wrapper Script?

Script Requirements

Location

Always: ./scripts/verify.sh

Behavior

1. Run all quality checks in sequence
2. Exit with code 0 if all pass
3. Exit with non-zero code on first failure
4. Print clear output indicating what's running

Checks to Include

Not all projects need all checks. Include what's relevant.

Script Constraints

The script must be:

Recommended additions:

• Print tool versions at start (helps debug CI vs local differences)
• Use set -euo pipefail for strict error handling
• Treat warnings as errors where applicable (e.g., cargo clippy -- -D warnings)

Examples by Project Type

Rust

bash
1#!/usr/bin/env bash
2set -euo pipefail
3
4echo "==> Running tests..."
5cargo test
6
7echo "==> Running clippy..."
8cargo clippy -- -D warnings
9
10echo "==> Checking formatting..."
11cargo fmt --check
12
13echo "==> All checks passed!"

Node.js / TypeScript

bash
1#!/usr/bin/env bash
2set -euo pipefail
3
4echo "==> Type checking..."
5npm run typecheck  # or: npx tsc --noEmit
6
7echo "==> Running tests..."
8npm test
9
10echo "==> Linting..."
11npm run lint  # or: npx eslint .
12
13echo "==> Checking formatting..."
14npx prettier --check .
15
16echo "==> All checks passed!"

Go

bash
1#!/usr/bin/env bash
2set -euo pipefail
3
4echo "==> Running tests..."
5go test ./...
6
7echo "==> Running linter..."
8golangci-lint run
9
10echo "==> Checking formatting..."
11test -z "$(gofmt -l .)" || { echo "Files need formatting"; exit 1; }
12
13echo "==> All checks passed!"

Python

bash
1#!/usr/bin/env bash
2set -euo pipefail
3
4echo "==> Running tests..."
5pytest
6
7echo "==> Type checking..."
8mypy .
9
10echo "==> Linting..."
11flake8
12
13echo "==> Checking formatting..."
14black --check .
15
16echo "==> All checks passed!"

Multi-language / Monorepo

bash
1#!/usr/bin/env bash
2set -euo pipefail
3
4echo "==> Backend (Rust)..."
5(cd backend && cargo test && cargo clippy -- -D warnings)
6
7echo "==> Frontend (TypeScript)..."
8(cd frontend && npm test && npm run lint)
9
10echo "==> All checks passed!"

Script Template

bash
1#!/usr/bin/env bash
2set -euo pipefail
3
4# Verify script for [PROJECT_NAME]
5# Runs all quality checks required before committing code.
6
7echo "==> Running tests..."
8# TODO: Add test command
9
10echo "==> Running linter..."
11# TODO: Add lint command
12
13echo "==> Checking formatting..."
14# TODO: Add format check command
15
16echo "==> All checks passed!"

Creating the Script

1. Create scripts/ directory if it doesn't exist
2. Create verify.sh using the template above
3. Fill in project-specific commands
4. Make executable: chmod +x scripts/verify.sh
5. Test it: ./scripts/verify.sh
6. Commit the script

Prerequisite for Plan Writing

Before running gap analysis or writing plans/IMPLEMENTATION_PLAN.md:

1. Check if ./scripts/verify.sh exists
2. If missing, stop and notify:

   ⚠️ Verification script not found.
   
   Before creating an implementation plan, create ./scripts/verify.sh
   See docs/writing-verify-script.md for instructions.
   

3. Once the script exists and passes, proceed with plan writing

Checklist

Before using the verification script:

Setup:

• Script exists at ./scripts/verify.sh
• Script is executable (chmod +x)
• Script uses set -euo pipefail

Checks included:

• Runs tests
• Runs linter (if project has one)
• Checks formatting (if project has formatter)
• Runs type checker (if applicable)

Constraints met:

• Non-interactive (no prompts or user input)
• Fails fast on first error
• CI-safe (no local-only dependencies)
• Deterministic (no flaky behavior)
• Exits 0 on success, non-zero on failure