@grimoire-cc/cli 0.6.3 → 0.7.1

package/packs/dev-pack/skills/gr.tdd-specialist/reference/anti-patterns.md

@@ -0,0 +1,166 @@
+# Testing Anti-Patterns
+
+Common testing mistakes that reduce test value and increase maintenance cost. These are language-agnostic — they apply to any test framework.
+
+## Table of Contents
+
+- [The Liar](#the-liar)
+- [The Giant](#the-giant)
+- [Excessive Setup](#excessive-setup)
+- [The Slow Poke](#the-slow-poke)
+- [The Peeping Tom](#the-peeping-tom)
+- [The Mockery](#the-mockery)
+- [The Inspector](#the-inspector)
+- [The Flaky Test](#the-flaky-test)
+
+## The Liar
+
+**What it is:** A test that passes but doesn't actually verify the behavior it claims to test. It gives false confidence.
+
+**How to spot it:**
+- Test name says "validates input" but assertions only check the return type
+- Assertions are too loose (`assert result is not None` instead of checking the actual value)
+- Test catches exceptions broadly and passes regardless
+
+**Fix:** Ensure assertions directly verify the specific behavior described in the test name. Every assertion should fail if the behavior breaks.
+
+```python
+# Bad — passes even if discount logic is completely wrong
+def test_apply_discount():
+    result = apply_discount(100, 10)
+    assert result is not None
+
+# Good — fails if the calculation is wrong
+def test_apply_discount_with_10_percent_returns_90():
+    result = apply_discount(100, 10)
+    assert result == 90.0
+```
+
+## The Giant
+
+**What it is:** A single test that verifies too many things. When it fails, you can't tell which behavior broke.
+
+**How to spot it:**
+- Test has more than 8-10 assertions
+- Test name uses "and" (e.g., "creates user and sends email and updates cache")
+- Multiple Act phases in one test
+
+**Fix:** Split into focused tests, each verifying one logical concept. Multiple assertions are fine if they verify aspects of the same behavior.
+
+```typescript
+// Bad — three unrelated behaviors in one test
+test('user registration works', () => {
+  const user = register({ name: 'Alice', email: 'alice@test.com' });
+  expect(user.id).toBeDefined();
+  expect(emailService.send).toHaveBeenCalled();
+  expect(cache.set).toHaveBeenCalledWith(`user:${user.id}`, user);
+  expect(auditLog.entries).toHaveLength(1);
+});
+
+// Good — separate tests for each behavior
+test('register with valid data creates user with id', () => { ... });
+test('register with valid data sends welcome email', () => { ... });
+test('register with valid data caches the user', () => { ... });
+test('register with valid data writes audit log entry', () => { ... });
+```
+
+## Excessive Setup
+
+**What it is:** Tests that require dozens of lines of setup before the actual test logic. Often signals that the code under test has too many dependencies.
+
+**How to spot it:**
+- Arrange section is 20+ lines
+- Multiple mocks configured with complex behaviors
+- Shared setup methods that configure things most tests don't need
+
+**Fix:** Use factory methods/builders for test data. Consider whether the code under test needs refactoring to reduce dependencies. Only set up what the specific test needs.
+
+```go
+// Bad — every test sets up the entire world
+func TestProcessOrder(t *testing.T) {
+    db := setupDatabase()
+    cache := setupCache()
+    logger := setupLogger()
+    emailClient := setupEmailClient()
+    validator := NewValidator(db)
+    processor := NewProcessor(cache)
+    service := NewOrderService(db, cache, logger, emailClient, validator, processor)
+    // ... 10 more lines of setup
+    result, err := service.ProcessOrder(ctx, order)
+    assert.NoError(t, err)
+}
+
+// Good — factory method hides irrelevant details
+func TestProcessOrder_WithValidOrder_Succeeds(t *testing.T) {
+    service := newTestOrderService(t)
+    result, err := service.ProcessOrder(ctx, validOrder())
+    assert.NoError(t, err)
+    assert.Equal(t, "processed", result.Status)
+}
+```
+
+## The Slow Poke
+
+**What it is:** Tests that are slow because they use real I/O, network calls, or sleeps. Slow tests get run less frequently and slow down the feedback loop.
+
+**How to spot it:**
+- `time.Sleep()`, `Thread.sleep()`, `setTimeout` in tests
+- Real HTTP calls, database connections, file system operations
+- Test suite takes more than a few seconds for unit tests
+
+**Fix:** Mock external dependencies. Use fake implementations for I/O. Replace time-based waits with event-based synchronization.
+
+## The Peeping Tom
+
+**What it is:** Tests that access private/internal state to verify behavior instead of testing through the public interface.
+
+**How to spot it:**
+- Reflection to access private fields
+- Testing internal method calls instead of observable results
+- Assertions on implementation details (internal data structures, private counters)
+
+**Fix:** Test through the public API. If you can't verify behavior through the public interface, the class may need a design change (e.g., expose a query method or extract a collaborator).
+
+## The Mockery
+
+**What it is:** Tests that mock so heavily that they're testing mock configurations rather than real behavior. Every dependency is mocked, including simple value objects.
+
+**How to spot it:**
+- More mock setup lines than actual test logic
+- Mocking concrete classes, value objects, or data structures
+- Test passes but the real system fails because mocks don't match reality
+
+**Fix:** Only mock at system boundaries (external services, databases, clocks). Use real implementations for in-process collaborators when practical.
+
+## The Inspector
+
+**What it is:** Tests that verify exact method calls and their order rather than outcomes. They break whenever the implementation changes, even if behavior is preserved.
+
+**How to spot it:**
+- `verify(mock, times(1)).method()` for every mock interaction
+- Assertions on call order
+- Test breaks when you refactor without changing behavior
+
+**Fix:** Verify state (the result) rather than interactions (how it got there). Only verify interactions for side effects that ARE the behavior (e.g., "email was sent").
+
+```java
+// Bad — breaks if implementation changes sort algorithm
+verify(sorter, times(1)).quickSort(any());
+verify(sorter, never()).mergeSort(any());
+
+// Good — verifies the outcome
+assertThat(result).isSortedAccordingTo(naturalOrder());
+```
+
+## The Flaky Test
+
+**What it is:** Tests that pass and fail intermittently without code changes. They erode trust in the test suite.
+
+**Common causes:**
+- Time-dependent logic (`new Date()`, `time.Now()`)
+- Random data without fixed seeds
+- Shared mutable state between tests
+- Race conditions in async tests
+- Dependency on test execution order
+
+**Fix:** Inject time as a dependency. Use fixed seeds for randomness. Ensure test isolation. Use proper async synchronization.

package/packs/dev-pack/skills/gr.tdd-specialist/reference/language-frameworks.md

@@ -0,0 +1,388 @@
+# Language & Framework Reference
+
+Quick-reference for each language's test ecosystem. Use this to apply framework-specific patterns after detecting the project's language.
+
+## Table of Contents
+
+- [JavaScript / TypeScript](#javascript--typescript)
+- [Python](#python)
+- [Go](#go)
+- [Rust](#rust)
+- [Java / Kotlin](#java--kotlin)
+- [C# / .NET](#c--net)
+- [Ruby](#ruby)
+
+## JavaScript / TypeScript
+
+### Frameworks
+
+| Framework | When to Use | Key Feature |
+|-----------|-------------|-------------|
+| **Vitest** | Vite projects, new TS projects | Fast, ESM-native, Jest-compatible API |
+| **Jest** | React (CRA), existing Jest projects | Mature ecosystem, wide adoption |
+| **Mocha + Chai** | Legacy projects, custom setups | Flexible, pluggable |
+| **Node test runner** | Node.js 20+, minimal deps | Built-in, zero dependencies |
+
+### Vitest / Jest Patterns
+
+```typescript
+import { describe, test, expect, vi, beforeEach } from 'vitest';
+
+describe('OrderService', () => {
+  let mockRepo: MockedObject<OrderRepository>;
+  let service: OrderService;
+
+  beforeEach(() => {
+    mockRepo = { save: vi.fn(), findById: vi.fn() };
+    service = new OrderService(mockRepo);
+  });
+
+  test('processOrder with valid order saves and returns id', async () => {
+    // Arrange
+    const order = createValidOrder();
+    mockRepo.save.mockResolvedValue({ id: '123' });
+
+    // Act
+    const result = await service.processOrder(order);
+
+    // Assert
+    expect(result.id).toBe('123');
+    expect(mockRepo.save).toHaveBeenCalledWith(order);
+  });
+
+  test('processOrder with invalid order throws ValidationError', async () => {
+    // Arrange
+    const order = createInvalidOrder();
+
+    // Act & Assert
+    await expect(service.processOrder(order)).rejects.toThrow(ValidationError);
+  });
+});
+```
+
+### File Conventions
+
+- `*.test.ts` / `*.spec.ts` (co-located or in `__tests__/`)
+- `vitest.config.ts` or `jest.config.ts` for configuration
+
+## Python
+
+### Frameworks
+
+| Framework | When to Use | Key Feature |
+|-----------|-------------|-------------|
+| **pytest** | Default choice, most projects | Fixtures, parametrize, plugins |
+| **unittest** | stdlib only, legacy projects | Built-in, class-based |
+
+### pytest Patterns
+
+```python
+import pytest
+from unittest.mock import Mock, AsyncMock, patch
+
+@pytest.fixture
+def mock_repo():
+    repo = Mock(spec=OrderRepository)
+    repo.save = AsyncMock(return_value=Order(id="123"))
+    return repo
+
+@pytest.fixture
+def service(mock_repo):
+    return OrderService(repository=mock_repo)
+
+async def test_process_order_with_valid_order_returns_id(service, mock_repo):
+    # Arrange
+    order = create_valid_order()
+
+    # Act
+    result = await service.process_order(order)
+
+    # Assert
+    assert result.id == "123"
+    mock_repo.save.assert_called_once_with(order)
+
+async def test_process_order_with_invalid_order_raises_validation_error(service):
+    # Arrange
+    order = create_invalid_order()
+
+    # Act & Assert
+    with pytest.raises(ValidationError, match="items cannot be empty"):
+        await service.process_order(order)
+
+@pytest.mark.parametrize("discount,expected", [
+    (0, 100.0),
+    (10, 90.0),
+    (50, 50.0),
+])
+def test_apply_discount_calculates_correctly(discount, expected):
+    assert apply_discount(100.0, discount) == expected
+```
+
+### File Conventions
+
+- `test_*.py` or `*_test.py` in `tests/` directory
+- `conftest.py` for shared fixtures
+- `pytest.ini` or `[tool.pytest.ini_options]` in `pyproject.toml`
+
+## Go
+
+### Frameworks
+
+| Framework | When to Use | Key Feature |
+|-----------|-------------|-------------|
+| **testing** (stdlib) | Always available | Built-in, no dependencies |
+| **testify** | Assertions + mocking | `assert`, `require`, `mock` packages |
+| **gomock** | Interface mocking | Code generation, strict expectations |
+
+### Go Patterns
+
+```go
+func TestProcessOrder_WithValidOrder_ReturnsID(t *testing.T) {
+    // Arrange
+    repo := new(MockOrderRepository)
+    repo.On("Save", mock.Anything).Return(&Order{ID: "123"}, nil)
+    service := NewOrderService(repo)
+
+    // Act
+    result, err := service.ProcessOrder(context.Background(), validOrder)
+
+    // Assert
+    require.NoError(t, err)
+    assert.Equal(t, "123", result.ID)
+    repo.AssertExpectations(t)
+}
+
+func TestProcessOrder_WithInvalidOrder_ReturnsError(t *testing.T) {
+    // Arrange
+    service := NewOrderService(nil)
+
+    // Act
+    _, err := service.ProcessOrder(context.Background(), invalidOrder)
+
+    // Assert
+    assert.ErrorIs(t, err, ErrValidation)
+}
+
+// Table-driven tests (Go idiom)
+func TestApplyDiscount(t *testing.T) {
+    tests := []struct {
+        name     string
+        price    float64
+        discount int
+        expected float64
+    }{
+        {"no discount", 100.0, 0, 100.0},
+        {"10 percent", 100.0, 10, 90.0},
+        {"50 percent", 100.0, 50, 50.0},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := ApplyDiscount(tt.price, tt.discount)
+            assert.Equal(t, tt.expected, result)
+        })
+    }
+}
+```
+
+### File Conventions
+
+- `*_test.go` in the same package (or `_test` package for black-box)
+- `go test ./...` to run all tests
+- `testdata/` for test fixtures
+
+## Rust
+
+### Patterns
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use mockall::predicate::*;
+
+    #[test]
+    fn process_order_with_valid_order_returns_id() {
+        // Arrange
+        let mut mock_repo = MockOrderRepository::new();
+        mock_repo.expect_save()
+            .returning(|_| Ok(Order { id: "123".into() }));
+        let service = OrderService::new(Box::new(mock_repo));
+
+        // Act
+        let result = service.process_order(&valid_order());
+
+        // Assert
+        assert_eq!(result.unwrap().id, "123");
+    }
+
+    #[test]
+    fn process_order_with_invalid_order_returns_error() {
+        // Arrange
+        let service = OrderService::new(Box::new(MockOrderRepository::new()));
+
+        // Act
+        let result = service.process_order(&invalid_order());
+
+        // Assert
+        assert!(matches!(result, Err(ServiceError::Validation(_))));
+    }
+}
+```
+
+### File Conventions
+
+- Tests in `#[cfg(test)] mod tests` at bottom of source file (unit tests)
+- Integration tests in `tests/` directory
+- `cargo test` to run all
+
+## Java / Kotlin
+
+### Frameworks
+
+| Framework | When to Use | Key Feature |
+|-----------|-------------|-------------|
+| **JUnit 5** | Default choice | Modern, extensible, parameterized |
+| **Mockito** | Mocking | Intuitive API, wide adoption |
+| **AssertJ** | Fluent assertions | Readable, discoverable API |
+
+### JUnit 5 + Mockito Patterns
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+    @Mock OrderRepository repository;
+    @InjectMocks OrderService service;
+
+    @Test
+    void processOrder_withValidOrder_returnsId() {
+        // Arrange
+        var order = createValidOrder();
+        when(repository.save(any())).thenReturn(new Order("123"));
+
+        // Act
+        var result = service.processOrder(order);
+
+        // Assert
+        assertThat(result.getId()).isEqualTo("123");
+        verify(repository).save(order);
+    }
+
+    @Test
+    void processOrder_withInvalidOrder_throwsValidationException() {
+        // Arrange
+        var order = createInvalidOrder();
+
+        // Act & Assert
+        assertThatThrownBy(() -> service.processOrder(order))
+            .isInstanceOf(ValidationException.class)
+            .hasMessageContaining("items cannot be empty");
+    }
+
+    @ParameterizedTest
+    @CsvSource({"0, 100.0", "10, 90.0", "50, 50.0"})
+    void applyDiscount_calculatesCorrectly(int discount, double expected) {
+        assertThat(applyDiscount(100.0, discount)).isEqualTo(expected);
+    }
+}
+```
+
+### File Conventions
+
+- `src/test/java/` mirroring `src/main/java/` structure
+- `*Test.java` suffix
+- `mvn test` or `gradle test`
+
+## C# / .NET
+
+**If the `grimoire:dotnet-unit-testing` skill is available, defer to it for full C#/.NET guidance.** It provides comprehensive xUnit, TUnit, Moq, and NSubstitute patterns.
+
+### Quick Reference (when dotnet skill is unavailable)
+
+| Framework | When to Use |
+|-----------|-------------|
+| **xUnit** | Default, most universal |
+| **NUnit** | If project already uses it |
+| **MSTest** | Microsoft-first shops |
+
+```csharp
+public class OrderServiceTests
+{
+    private readonly Mock<IOrderRepository> _mockRepo;
+    private readonly OrderService _sut;
+
+    public OrderServiceTests()
+    {
+        _mockRepo = new Mock<IOrderRepository>();
+        _sut = new OrderService(_mockRepo.Object);
+    }
+
+    [Fact]
+    public async Task ProcessOrder_WithValidOrder_ReturnsId()
+    {
+        // Arrange
+        var order = CreateValidOrder();
+        _mockRepo.Setup(r => r.SaveAsync(It.IsAny<Order>()))
+            .ReturnsAsync(new Order { Id = "123" });
+
+        // Act
+        var result = await _sut.ProcessOrderAsync(order);
+
+        // Assert
+        Assert.Equal("123", result.Id);
+    }
+}
+```
+
+### File Conventions
+
+- `Tests/` or `*.Tests/` project mirroring source structure
+- `*Tests.cs` suffix
+- `dotnet test` to run
+
+## Ruby
+
+### Frameworks
+
+| Framework | When to Use |
+|-----------|-------------|
+| **RSpec** | Default, most Ruby projects |
+| **Minitest** | stdlib, Rails default |
+
+### RSpec Patterns
+
+```ruby
+RSpec.describe OrderService do
+  let(:repository) { instance_double(OrderRepository) }
+  let(:service) { described_class.new(repository: repository) }
+
+  describe '#process_order' do
+    context 'with a valid order' do
+      it 'returns the order id' do
+        # Arrange
+        order = build(:order, :valid)
+        allow(repository).to receive(:save).and_return(Order.new(id: '123'))
+
+        # Act
+        result = service.process_order(order)
+
+        # Assert
+        expect(result.id).to eq('123')
+        expect(repository).to have_received(:save).with(order)
+      end
+    end
+
+    context 'with an invalid order' do
+      it 'raises ValidationError' do
+        order = build(:order, :invalid)
+        expect { service.process_order(order) }.to raise_error(ValidationError)
+      end
+    end
+  end
+end
+```
+
+### File Conventions
+
+- `spec/` directory mirroring `lib/` or `app/` structure
+- `*_spec.rb` suffix
+- `bundle exec rspec` to run

package/packs/dev-pack/skills/gr.tdd-specialist/reference/tdd-workflow-patterns.md

@@ -0,0 +1,135 @@
+# TDD Workflow Patterns
+
+Guidance on the test-driven development process, when to apply it, and advanced techniques.
+
+## Table of Contents
+
+- [Red-Green-Refactor](#red-green-refactor)
+- [Transformation Priority Premise](#transformation-priority-premise)
+- [When to Use TDD](#when-to-use-tdd)
+- [When TDD Is Less Effective](#when-tdd-is-less-effective)
+- [BDD and ATDD Extensions](#bdd-and-atdd-extensions)
+
+## Red-Green-Refactor
+
+The core TDD cycle, repeated in small increments:
+
+### 1. Red — Write a Failing Test
+
+Write the smallest test that describes the next piece of behavior. The test MUST fail before you write any production code. A test that passes immediately provides no confidence.
+
+**Rules:**
+- Write only ONE test at a time
+- The test should compile/parse but fail at the assertion
+- If the test passes immediately, it's either trivial or testing existing behavior
+
+### 2. Green — Make It Pass
+
+Write the MINIMUM code to make the failing test pass. Do not add extra logic, handle cases not yet tested, or optimize.
+
+**Rules:**
+- Write the simplest code that makes the test pass
+- It's OK to hardcode values initially — the next test will force generalization
+- Do not add code for future tests
+- All existing tests must still pass
+
+### 3. Refactor — Clean Up
+
+With all tests green, improve the code structure without changing behavior. Tests give you the safety net.
+
+**Rules:**
+- No new functionality during refactoring
+- All tests must remain green after each refactoring step
+- Remove duplication, improve naming, extract methods
+- Refactor both production code AND test code
+
+### Cycle Length
+
+Each Red-Green-Refactor cycle should take 1-10 minutes. If you're spending more than 10 minutes in the Red or Green phase, the step is too large — break it down.
+
+## Transformation Priority Premise
+
+Kent Beck's insight: when going from Red to Green, prefer simpler transformations over complex ones. Listed from simplest to most complex:
+
+1. **Constant** — return a hardcoded value
+2. **Scalar** — replace constant with a variable
+3. **Direct** — replace unconditional with conditional (if/else)
+4. **Collection** — operate on a collection instead of a scalar
+5. **Iteration** — add a loop
+6. **Recursion** — add recursive call
+7. **Assignment** — replace computed value with mutation
+
+**Example — building FizzBuzz with TDD:**
+
+```
+Test 1: input 1 → "1"          Transformation: Constant
+Test 2: input 2 → "2"          Transformation: Scalar (use the input)
+Test 3: input 3 → "Fizz"       Transformation: Direct (add if)
+Test 4: input 5 → "Buzz"       Transformation: Direct (add another if)
+Test 5: input 15 → "FizzBuzz"  Transformation: Direct (add combined if)
+Test 6: input 1-15 → full list Transformation: Iteration (generalize)
+```
+
+By following this priority, you avoid over-engineering early and let the design emerge naturally from the tests.
+
+## When to Use TDD
+
+TDD is most valuable when:
+
+- **Business logic** — Complex rules, calculations, state machines. TDD forces you to think through all cases before implementing.
+- **Algorithm development** — Sorting, parsing, validation, transformation logic. Tests serve as a specification.
+- **Bug fixes** — Write a test that reproduces the bug first (Red), then fix it (Green). This prevents regressions.
+- **API/interface design** — Writing tests first helps you design interfaces from the consumer's perspective.
+- **Refactoring** — Ensure tests exist before refactoring. If they don't, write characterization tests first, then refactor.
+
+## When TDD Is Less Effective
+
+TDD is not universally optimal. Use judgment:
+
+- **UI/visual components** — Layout, styling, animations are hard to express as unit tests. Use visual regression testing or snapshot tests instead.
+- **Exploratory/prototype code** — When you don't know what to build yet, writing tests first slows exploration. Spike first, then write tests.
+- **Thin integration layers** — Simple pass-through code (e.g., a controller that calls a service) may not benefit from test-first approach. Integration tests are more valuable here.
+- **Infrastructure/glue code** — Database migrations, config files, build scripts. Test these with integration or end-to-end tests.
+- **External API wrappers** — Thin clients wrapping external APIs are better tested with integration tests against the real (or sandboxed) API.
+
+For these cases, write tests AFTER the implementation (test-last), but still write them.
+
+## BDD and ATDD Extensions
+
+### Behavior-Driven Development (BDD)
+
+BDD extends TDD by using natural language to describe behavior. Useful when tests need to be readable by non-developers.
+
+**Given-When-Then** structure:
+
+```gherkin
+Given a cart with items totaling $100
+When a 10% discount is applied
+Then the total should be $90
+```
+
+Maps to test code:
+
+```python
+def test_cart_with_10_percent_discount_totals_90():
+    # Given
+    cart = Cart(items=[Item(price=100)])
+
+    # When
+    cart.apply_discount(PercentageDiscount(10))
+
+    # Then
+    assert cart.total == 90.0
+```
+
+### Acceptance TDD (ATDD)
+
+Write high-level acceptance tests before implementing a feature. These tests describe the feature from the user's perspective and drive the overall design. Unit tests (via TDD) then drive the implementation of each component.
+
+**Flow:**
+1. Write acceptance test (fails — Red)
+2. Use TDD to implement components needed to pass it
+3. Acceptance test passes (Green)
+4. Refactor
+
+ATDD is most valuable for features with clear acceptance criteria and when working with product owners or stakeholders.