validating-pre-commit

saleor's avatarfrom saleor

Runs quality gate checks before commit or push. Executes lint fixes, TypeScript compilation, tests, and CI validation. Reproduces CI failures locally. Triggers on: pre-commit, pre-push, quality check, CI check, lint check, type check, validate changes, check:fix, pnpm test.

⭐20stars🔀2forks📁View on GitHub🕐Updated Dec 15, 2025

When & Why to Use This Skill

This Claude skill acts as an automated quality gatekeeper for software development workflows. It streamlines the pre-commit and pre-push process by executing a mandatory checklist that includes linting auto-fixes, TypeScript compilation, comprehensive testing, and CI validation. By reproducing CI environments locally, it helps developers catch and resolve errors early, ensuring code integrity and significantly reducing pipeline failures.

Use Cases

  • Automated Code Formatting: Automatically fix Biome linting and formatting issues before committing to ensure strict adherence to project style guides without manual intervention.
  • Local CI Debugging: Reproduce and resolve complex CI/CD pipeline failures on a local machine using the exact validation scripts and environment checks used in production.
  • Strict Type Validation: Perform deep TypeScript compilation checks (tsc --noEmit) to identify implicit 'any' types, missing exports, and potential null pointer exceptions before code is pushed.
  • Regression Prevention: Execute the full suite of unit and integration tests after significant refactoring to verify that new updates haven't introduced breaking changes to existing functionality.
  • E2E CLI Verification: Conduct end-to-end testing protocols for CLI tools, including introspection and deployment idempotency checks, to ensure operational stability and consistency.
namevalidating-pre-commit
description"Runs quality gate checks before commit or push. Executes lint fixes, TypeScript compilation, tests, and CI validation. Reproduces CI failures locally. Triggers on: pre-commit, pre-push, quality check, CI check, lint check, type check, validate changes, check:fix, pnpm test."
allowed-tools"Read, Bash(pnpm:*), Bash(npx:*), Bash(rm:*)"

Pre-Commit Quality Gate

Purpose

Ensure all code quality standards are met before committing or pushing changes. This skill runs the mandatory quality checklist and reports any failures with actionable fixes.

When to Use

  • Before creating a commit
  • Before pushing to remote
  • After making significant changes
  • When CI is failing and you need to reproduce locally
  • To validate changes pass all quality gates

Table of Contents

Mandatory Quality Checklist

Execute these steps in order. All must pass before committing.

Step 1: Auto-Fix Linting and Formatting

pnpm check:fix

Purpose: Auto-fix all Biome linting and formatting issues.

Common Fixes Applied:

  • Import organization
  • Trailing commas
  • Quote style
  • Indentation
  • Line endings

If Issues Remain: Some issues cannot be auto-fixed. Review the output and manually address:

  • Complexity warnings
  • Unused variables
  • Type errors

Step 2: Verify TypeScript Compilation

pnpm build

Purpose: Ensure the project compiles without errors.

Common Failures:

  • Type mismatches
  • Missing exports
  • Import resolution errors

Troubleshooting:

  • Check recent changes for type errors
  • Verify imports match exports
  • Ensure new files are properly typed

Step 3: Run All Tests

pnpm test

Purpose: Ensure all tests pass.

If Tests Fail:

  1. Read the failure message carefully
  2. Check if the test expectation matches new behavior
  3. Update test or fix implementation accordingly
  4. Re-run affected tests: pnpm test -- --filter=<test-file>

Step 4: Strict TypeScript Check

npx tsc --noEmit

Purpose: Validate TypeScript with strict checking (catches more than build).

Common Issues:

  • Implicit any types
  • Unused imports/variables
  • Stricter null checking

Step 5: Final CI Validation

pnpm check:ci

Purpose: Run the same checks that CI will run.

This Combines:

  • Linting without auto-fix
  • Format checking
  • TypeScript compilation

E2E CLI Testing Protocol

When to Run: Before pushing changes that affect core CLI functionality (commands, services, repositories).

Full E2E Validation Workflow

# Test credentials
--url=https://store-rzalldyg.saleor.cloud/graphql/
--token=YbE8g7ZNl0HkxdK92pfNdLJVQwV0Xs

# 1. Clean slate
rm -rf config.yml

# 2. Fresh introspection
pnpm dev introspect --url=<URL> --token=<TOKEN>

# 3. Make test changes to config.yml (optional)

# 4. Deploy changes
pnpm dev deploy --url=<URL> --token=<TOKEN>

# 5. Test idempotency (deploy again - should have no changes)
pnpm dev deploy --url=<URL> --token=<TOKEN>

# 6. Clean again
rm config.yml

# 7. Re-introspect
pnpm dev introspect --url=<URL> --token=<TOKEN>

# 8. Verify no drift (should show no changes)
pnpm dev diff --url=<URL> --token=<TOKEN>

Success Criteria:

  • Step 5 shows no changes (idempotency)
  • Step 8 shows no diff (round-trip consistency)

Quick Reference Commands

Check Command Purpose
All checks ./scripts/validate-all.sh Run all checks in sequence
Auto-fix pnpm check:fix Fix lint/format issues
Build pnpm build Compile TypeScript
Test pnpm test Run all tests
Type check npx tsc --noEmit Strict TS validation
CI check pnpm check:ci Full CI validation
Lint only pnpm lint Check linting
Format only pnpm format Check formatting

One-Command Validation

Run all quality checks in sequence:

./.claude/skills/pre-commit-quality/scripts/validate-all.sh

This script executes all 5 steps of the mandatory checklist and stops on first failure.

Common Failure Patterns

Biome Errors

"Unexpected any":

// BAD
const data: any = response;

// GOOD
const data: ResponseType = response;

"Unused import": Remove the import or use it.

"Prefer template literal":

// BAD
const msg = 'Hello ' + name;

// GOOD
const msg = `Hello ${name}`;

TypeScript Errors

"Object is possibly undefined":

// BAD
const value = obj.prop.nested;

// GOOD
const value = obj?.prop?.nested;
// OR with assertion if certain
const value = obj!.prop!.nested; // Only if you're sure

"Type 'X' is not assignable to type 'Y'": Check the type definitions and ensure compatibility.

Test Failures

Mock not returning expected value:

vi.mocked(mockService.method).mockResolvedValue(expectedValue);

Assertion mismatch: Review the expected vs actual output and update accordingly.

Automated Checks

The project has pre-push hooks configured via Husky:

  • .husky/pre-push: Generates schema documentation

These run automatically - no manual action needed.

References

  • scripts/validate-all.sh - One-command validation script
  • {baseDir}/docs/CLAUDE.md - Full pre-push checklist
  • {baseDir}/docs/TESTING_PROTOCOLS.md - E2E testing details
  • {baseDir}/biome.json - Linting configuration
  • Code standards: See reviewing-typescript-code for quality criteria
  • CI integration: See managing-github-ci for workflow troubleshooting
  • Test failures: See analyzing-test-coverage for test debugging

Quick Reference Rule

For a condensed quick reference, see .claude/rules/deployment-safety.md (always loaded - applies to all files).