refactor: improve DRY and add pre-PR checklist

[kevalyq]

Summary

This PR implements improvements identified in the Issue #50 comprehensive review (docs/PR_REVIEW_ISSUE50.md).

Improvements:

1. DRY Refactoring - Extract magic constants and eliminate code duplication
2. Pre-PR Checklist - Add comprehensive quality checklist to DEVELOPMENT.md

Changes

1. Extract Magic Constants in TenantKey

Before:

mkdir($dir, 0700, true);
hash_hmac('sha256', $plaintext, $idxKey, true);

After:

private const KEY_DIRECTORY_PERMISSIONS = 0700;
private const HMAC_ALGORITHM = 'sha256';

mkdir($dir, self::KEY_DIRECTORY_PERMISSIONS, true);
hash_hmac(self::HMAC_ALGORITHM, $plaintext, $idxKey, true);

Benefit: Improves maintainability and makes intent explicit.

---

2. Use NormalizesPersonFields Trait in RebuildIndexCommand

Before:

$normalized = strtolower(trim($emailPlain));
$normalized = preg_replace('/\D/', '', $phonePlain);

After:

use NormalizesPersonFields;

$normalized = $this->normalizeEmail($emailPlain);
$normalized = $this->normalizePhone($phonePlain);

Benefit: Eliminates code duplication, ensures consistent normalization logic across PersonObserver, PersonRepository, and RebuildIndexCommand.

---

3. Add Pre-PR Quality Checklist to DEVELOPMENT.md

Added comprehensive checklist covering:

• ✅ Parallel test execution (catches race conditions)
• 🔍 Code duplication checks (grep patterns + PHPStan)
• 🔢 Magic number detection
• 📝 Conventional commit format
• 📊 PR size discipline (<600 LOC guideline)
• 🤖 Copilot review workflow

Quick Pre-PR Command:

ddev . ./vendor/bin/pest --parallel && \
ddev . ./vendor/bin/pint && \
ddev . ./vendor/bin/phpstan analyse && \
echo "✅ Ready for PR!"

Benefit: Documents best practices learned from Issue #50, prevents future follow-up PRs for avoidable issues.

Metrics

• LOC Changed: 120 lines (+112, -8)
  • TenantKey.php: +8 LOC (2 constants)
  • RebuildIndexCommand.php: +3 LOC (use trait, remove duplication)
  • DEVELOPMENT.md: +101 LOC (Pre-PR checklist)
• Tests: 114 passing, 332 assertions, 0 failures
• PHPStan: Level 9, 0 errors
• Pint: PSR-12, 0 violations

Review Impact

These changes address recommendations from Issue #50 comprehensive review:

• DRY Adherence: 4/5 → 5/5 (code duplication eliminated)
• Process Documentation: Enhanced for future PRs
• Code Quality: Maintainability improved through named constants

Testing

All existing tests pass without modification - refactoring is transparent to behavior.

ddev . ./vendor/bin/pest
# Tests:    114 passed (332 assertions)
# Duration: 9.90s

Checklist

• Parallel test execution passes
• No code duplication (grep + PHPStan check)
• Magic numbers replaced with named constants
• All quality gates passing (Pint, PHPStan, PEST)
• Conventional commit format used
• PR size <600 LOC ✅ (120 LOC)
• Pre-PR checklist followed (dogfooding our own docs!)

Related

• Issue SecPal API: Multi-tenant security, field encryption & blind indexes, Sanctum & Spatie Teams — TDD/PEST, DRY, best practices #50 - Multi-Tenant Encryption (completed)
• docs/PR_REVIEW_ISSUE50.md - Comprehensive review with recommendations

[Copilot]

Pull Request Overview

This PR refactors code to eliminate magic numbers and reduce duplication by extracting normalization logic into a trait. The changes improve maintainability by replacing hardcoded values with named constants and consolidating repeated normalization patterns.

• Extracted email and phone normalization logic into a reusable NormalizesPersonFields trait
• Replaced magic numbers (0700, 'sha256') with named class constants
• Updated RebuildIndexCommand to use the trait instead of inline normalization logic

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
app/Models/TenantKey.php	Introduced constants for directory permissions (0700) and HMAC algorithm (sha256) to replace magic values
app/Console/Commands/RebuildIndexCommand.php	Added NormalizesPersonFields trait usage and replaced inline normalization with trait methods
DEVELOPMENT.md	Added comprehensive pre-PR quality checklist with examples of magic numbers, code duplication checks, and quality gate commands