validating-pre-commit

name	validating-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
  • Step 1: Auto-Fix Linting and Formatting
  • Step 2: Verify TypeScript Compilation
  • Step 3: Run All Tests
  • Step 4: Strict TypeScript Check
  • Step 5: Final CI Validation
• E2E CLI Testing Protocol
• Quick Reference Commands
• Common Failure Patterns
• Automated Checks
• References

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

Related Skills

• 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).