rhachet-roles-ehmpathy 1.13.6 → 1.13.7

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/howto.write.bdd.[lesson].md

@@ -0,0 +1,280 @@
+# How to Write BDD Style Tests
+
+This guide explains the pattern for writing integration tests using `test-fns` with `given`, `when`, `then`, and `useBeforeAll`.
+
+## Core Pattern
+
+```typescript
+import { given, when, then, useBeforeAll } from 'test-fns';
+
+describe('featureName', () => {
+  // Shared setup for all tests in the describe block
+  const dbConnection = useBeforeAll(() => getDatabaseConnection());
+  afterAll(async () => dbConnection.end());
+
+  given('[case1] description of the initial state', () => {
+    // Setup specific to this case, shared across all when/then blocks
+    const scene = useBeforeAll(async () => {
+      // Create test data
+      const entity = await createEntity({ dbConnection });
+      return { entity };
+    });
+
+    when('[t0] action or event occurs', () => {
+      then('expected outcome', async () => {
+        // Execute and verify using scene.entity
+        const result = await performAction({ id: scene.entity.id });
+        expect(result).toEqual(expectedValue);
+      });
+    });
+
+    when('[t1] different action occurs', () => {
+      then('different expected outcome', async () => {
+        // Another test using the same scene
+        const result = await performOtherAction({ id: scene.entity.id });
+        expect(result).toEqual(otherExpectedValue);
+      });
+    });
+  });
+});
+```
+
+## Key Principles
+
+### 1. Wrap Everything in `describe`
+
+All tests for a feature should be wrapped in a single `describe` block:
+
+```typescript
+describe('syncPhoneFromWhodis', () => {
+  // all given/when/then blocks go here
+});
+```
+
+### 2. Use `useBeforeAll` for shared resources
+
+Instead of `let` + `beforeAll` + `afterAll`:
+
+e.g.,
+```typescript
+// ❌ Don't do this
+let dbConnection: DatabaseConnection;
+beforeAll(async () => {
+  dbConnection = await getDatabaseConnection();
+});
+afterAll(async () => {
+  await dbConnection.end();
+});
+
+// ✅ Do this
+const dbConnection = useBeforeAll(() => getDatabaseConnection());
+afterAll(async () => dbConnection.end());
+```
+
+### 3. Label given(scenes) with `[caseN]`
+
+Each `given` block should have a unique case label:
+
+```typescript
+given('[case1] doer with outdated phone', () => { ... });
+given('[case2] doer with matching phone', () => { ... });
+given('[case3] doer does not exist', () => { ... });
+```
+
+### 4. Label when(event) with `[tN]`
+
+Each `when` block should have an event time index label. The counter resets within each `given` block:
+
+```typescript
+given('[case1] first scenario', () => {
+  when('[t0] command executed in PLAN mode', () => { ... });
+  when('[t1] command executed in EXECUTE mode', () => { ... });
+});
+
+given('[case2] second scenario', () => {
+  when('[t0] first action', () => { ... });  // counter resets to 0
+  when('[t1] second action', () => { ... });
+});
+```
+
+### 5. One Behavioral Assertion per `then` Block
+
+Each `then` block should test a single behavioral assertion. This makes test failures more precise and test names more descriptive:
+
+```typescript
+// ❌ Don't do this - multiple assertions in one then
+when('[t0] command executed in PLAN mode', () => {
+  then('decision is UPDATE and doer remains unchanged', async () => {
+    const result = await command({ mode: 'PLAN' });
+    expect(result.decision).toEqual('UPDATE');
+    expect(result.before.doer.contactPhoneNumber).toEqual('+13175550200');
+
+    const doerAfter = await doerDao.findByUnique({ dbConnection, userUuid });
+    expect(doerAfter?.contactPhoneNumber).toEqual('+13175550200');
+  });
+});
+
+// ✅ Do this - separate then blocks for each behavioral assertion
+when('[t0] command executed in PLAN mode', () => {
+  then('decision is "UPDATE"', async () => {
+    const result = await command({ mode: 'PLAN' });
+    expect(result.decision).toEqual('UPDATE');
+  });
+
+  then('before.doer.contactPhoneNumber is "+13175550200"', async () => {
+    const result = await command({ mode: 'PLAN' });
+    expect(result.before.doer.contactPhoneNumber).toEqual('+13175550200');
+  });
+
+  then('doer contactPhoneNumber remains unchanged', async () => {
+    await command({ mode: 'PLAN' });
+    const doerAfter = await doerDao.findByUnique({ dbConnection, userUuid });
+    expect(doerAfter?.contactPhoneNumber).toEqual('+13175550200');
+  });
+});
+```
+
+### 6. Use `scene` for Shared Test Data
+
+When multiple `when/then` blocks need the same test data, use `useBeforeAll` to create a `scene`:
+
+```typescript
+given('[case1] description', () => {
+  const scene = useBeforeAll(async () => {
+    const doer = await createDoer({ dbConnection });
+    const provider = await createProvider({ dbConnection, doerId: doer.id });
+    return { doer, provider };
+  });
+
+  when('[t0] first test', () => {
+    then('outcome', async () => {
+      // Access scene.doer and scene.provider
+      const result = await action({ doerId: scene.doer.id });
+    });
+  });
+
+  when('[t1] second test', () => {
+    then('outcome', async () => {
+      // Same scene is reused
+      const result = await otherAction({ providerId: scene.provider.id });
+    });
+  });
+});
+```
+
+### 7. Cases Without Setup
+
+If a case doesn't need setup (e.g., testing error handling with invalid input), skip the `scene`:
+
+```typescript
+given('[case4] valid userUuid', () => {
+  when('[t7] Whodis user cannot be found', () => {
+    then('command throws error', async () => {
+      await expect(
+        command({ userUuid: '00000000-0000-0000-0000-000000000001' }),
+      ).rejects.toThrow('Whodis user not found');
+    });
+  });
+});
+```
+
+## Complete Example
+
+```typescript
+import { given, when, then, useBeforeAll } from 'test-fns';
+import { getDatabaseConnection } from '../../utils/database/getDatabaseConnection';
+import { myCommand } from './myCommand';
+
+describe('myCommand', () => {
+  const dbConnection = useBeforeAll(() => getDatabaseConnection());
+  afterAll(async () => dbConnection.end());
+
+  given('[case1] entity exists with state A', () => {
+    const scene = useBeforeAll(async () => {
+      const entity = await createEntity({
+        dbConnection,
+        state: 'A',
+      });
+      return { entity };
+    });
+
+    when('[t0] command executed in PLAN mode', () => {
+      then('decision is "UPDATE"', async () => {
+        const result = await myCommand({
+          entityId: scene.entity.id,
+          mode: 'PLAN',
+        });
+        expect(result.decision).toEqual('UPDATE');
+      });
+
+      then('entity state remains "A"', async () => {
+        await myCommand({ entityId: scene.entity.id, mode: 'PLAN' });
+        const entityAfter = await findEntity({ dbConnection, id: scene.entity.id });
+        expect(entityAfter.state).toEqual('A');
+      });
+    });
+
+    when('[t1] command executed in EXECUTE mode', () => {
+      then('decision is "UPDATE"', async () => {
+        const result = await myCommand({
+          entityId: scene.entity.id,
+          mode: 'EXECUTE',
+        });
+        expect(result.decision).toEqual('UPDATE');
+      });
+
+      then('after.state is "B"', async () => {
+        const result = await myCommand({
+          entityId: scene.entity.id,
+          mode: 'EXECUTE',
+        });
+        expect(result.after.state).toEqual('B');
+      });
+
+      then('entity state is updated to "B"', async () => {
+        await myCommand({ entityId: scene.entity.id, mode: 'EXECUTE' });
+        const entityAfter = await findEntity({ dbConnection, id: scene.entity.id });
+        expect(entityAfter.state).toEqual('B');
+      });
+    });
+  });
+
+  given('[case2] entity already in state B', () => {
+    const scene = useBeforeAll(async () => {
+      const entity = await createEntity({
+        dbConnection,
+        state: 'B',
+      });
+      return { entity };
+    });
+
+    when('[t0] command executed', () => {
+      then('decision is "NOCHANGE"', async () => {
+        const result = await myCommand({
+          entityId: scene.entity.id,
+          mode: 'EXECUTE',
+        });
+        expect(result.decision).toEqual('NOCHANGE');
+      });
+    });
+  });
+
+  given('[case3] invalid entityId', () => {
+    when('[t0] command executed', () => {
+      then('throws error', async () => {
+        await expect(
+          myCommand({ entityId: 'invalid-id', mode: 'PLAN' }),
+        ).rejects.toThrow('Entity not found');
+      });
+    });
+  });
+});
+```
+
+## Benefits
+
+1. **Readable test output**: Test names clearly show the scenario being tested
+2. **Efficient setup**: `useBeforeAll` runs once per `given` block, not per test
+3. **Immutable references**: `const scene` and `const dbConnection` prevent accidental reassignment
+4. **Clear labeling**: `[caseN]` and `[tN]` labels make it easy to identify and discuss specific tests
+5. **Black-box testing**: Tests interact only through the contract layer, not internal implementations

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/prefer.datadriven.md

@@ -0,0 +1,41 @@
+when possible, prefer data driven, caselist based, tests
+
+this is especially applicable for unit tests, which often evaluate a transform
+
+---
+
+
+for example
+
+
+```ts
+
+const TEST_CASES = [
+  {
+    description: 'capitalizes the first word in a sentence',
+    given: {
+      input: 'the bird is in the basket',
+    },
+    expect: {
+      output: 'The bird is in the basket',
+    }
+  },
+  {
+    description: 'retains existing capitals in the sentence',
+    given: {
+      input: 'that Doctor Goose is a loon!',
+    },
+    expect: {
+      output: 'That Doctor Goose is a loon!',
+    }
+  },
+]
+
+describe('asSentenceCase', () => {
+  TEST_CASES.map(thisCase => test(thisCase.description, () => {
+    const output = asSentenceCase(thisCase.given.input);
+    expect(output).toEqual(thisCase.expect.output);
+  }))
+})
+
+```

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/ref.test-fns.[readme].md

@@ -0,0 +1,185 @@
+# test-fns
+
+![ci_on_commit](https://github.com/ehmpathy/test-fns/workflows/ci_on_commit/badge.svg)
+![deploy_on_tag](https://github.com/ehmpathy/test-fns/workflows/deploy_on_tag/badge.svg)
+
+write usecase driven tests systematically for simpler, safer, and more readable code
+
+# purpose
+
+establishes a pattern of writing tests for simpler, safer, and more readable code.
+
+by defining tests in terms of usecases (`given`, `when`, `then`) your tests are
+- simpler to write
+- easier to read
+- safer to trust
+
+# install
+
+```sh
+npm install --save test-fns
+```
+
+# use
+
+```ts
+type Plant = { id: number, hydration: 'DRY' | 'WET' };
+const doesPlantNeedWater = (plant: Plant) => plant.hydration === 'DRY';
+
+describe('doesPlantNeedWater', () => {
+  given('a plant', () => {
+    when('the plant doesnt have enough water', () => {
+      const plant: Plant = {
+        id: 7,
+        hydration: 'DRY',
+      };
+      then('it should return true', () => {
+        expect(doesPlantNeedWater(plant)).toEqual(true)
+      })
+    })
+  })
+})
+```
+
+produces
+
+```sh
+ PASS  src/givenWhenThen.test.ts
+  doesPlantNeedWater
+    given: a plant
+      when: the plant doesnt have enough water
+        ✓ then: it should return true (1 ms)
+```
+
+# features
+
+
+### .runIf(condition) && .skipIf(condition)
+
+skip running the suite if the condition is not met
+
+```ts
+describe('your test', () => {
+  given.runIf(onLocalMachine)('some test that should only run locally', () => {
+    then.skipIf(onProduction)('some test that should not run against production', () => {
+      expect(onProduction).toBeFalse()
+    })
+  })
+})
+```
+
+### usePrep
+
+prepare test scenarios within a .given/.when block asynchronously, without any `let`s or `beforeAll`s
+
+`usePrep` accepts a `mode` option to control when setup runs:
+- `mode: 'beforeAll'` - runs setup once for all tests (default)
+- `mode: 'beforeEach'` - runs setup fresh before each test
+
+```ts
+given('an overdue invoice', () => {
+  const invoice = usePrep(async () => {
+    const invoiceOverdue = await ... // your logic
+    return invoiceOverdue;
+  })
+
+  then('it should invoke a reminder', async () => {
+    const result = await nurtureInvoice({ invoice }, context)
+    expect(result.sent.reminder).toEqual(true)
+  })
+})
+```
+
+**useBeforeAll and useBeforeEach are convenience wrappers** around `usePrep`:
+- `useBeforeAll(setup)` is equivalent to `usePrep(setup, { mode: 'beforeAll' })`
+- `useBeforeEach(setup)` is equivalent to `usePrep(setup, { mode: 'beforeEach' })`
+
+Use the named functions for clarity about when setup runs.
+
+### useBeforeAll
+
+prepare test resources once for all tests in a suite, optimizing setup time for expensive operations
+
+```ts
+describe('spaceship refueling system', () => {
+  given('a spaceship that needs to refuel', () => {
+    const spaceship = useBeforeAll(async () => {
+      // This runs once before all tests in this suite
+      const ship = await prepareExampleSpaceship();
+      await ship.dock();
+      return ship;
+    });
+
+    when('no changes are made', () => {
+      then('it should be docked', async () => {
+        expect(spaceship.isDocked).toEqual(true);
+      });
+
+      then('it should need fuel', async () => {
+        expect(spaceship.fuelLevel).toBeLessThan(spaceship.fuelCapacity);
+      });
+    });
+
+    when('it connects to the fuel station', () => {
+      const result = useBeforeAll(async () => await spaceship.connectToFuelStation());
+
+      then('it should be connected', async () => {
+        expect(result.connected).toEqual(true);
+      });
+
+      then('it should calculate required fuel', async () => {
+        expect(result.fuelNeeded).toBeGreaterThan(0);
+      });
+    });
+  });
+});
+```
+
+### useBeforeEach
+
+prepare fresh test resources before each test, ensuring test isolation
+
+```ts
+describe('spaceship combat system', () => {
+  given('a spaceship in battle', () => {
+    // This runs before each test, ensuring a fresh spaceship
+    const spaceship = useBeforeEach(async () => {
+      const ship = await prepareExampleSpaceship();
+      await ship.resetShields();
+      return ship;
+    });
+
+    when('no changes are made', () => {
+      then('it should have full shields', async () => {
+        expect(spaceship.shields).toEqual(100);
+      });
+
+      then('it should be ready for combat', async () => {
+        expect(spaceship.status).toEqual('READY');
+      });
+    });
+
+    when('it takes damage', () => {
+      const result = useBeforeEach(async () => await spaceship.takeDamage(25));
+
+      then('it should reduce shield strength', async () => {
+        expect(spaceship.shields).toEqual(75);
+      });
+
+      then('it should return damage report', async () => {
+        expect(result.damageReceived).toEqual(25);
+      });
+    });
+  });
+});
+```
+
+**When to use each:**
+- `useBeforeAll`: Use when setup is expensive (database connections, API calls) and tests don't modify the resource
+- `useBeforeEach`: Use when tests modify the resource and need isolation between runs
+- `usePrep`: The base function that powers both - use when you want explicit control over the mode or need to dynamically choose between `beforeAll` and `beforeEach`
+
+**Key differences:**
+- All three functions (`usePrep`, `useBeforeAll`, `useBeforeEach`) create a proxy that defers setup until the test framework's lifecycle hooks run
+- `useBeforeAll` and `useBeforeEach` are just clearer, more readable shortcuts for `usePrep` with a specific mode
+- Choose based on readability: use `useBeforeAll`/`useBeforeEach` for explicit intent, or `usePrep` when mode needs to be configurable

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/whento.snapshots.[lesson].md

@@ -0,0 +1,23 @@
+use snapshots whenever output artifacts are created
+
+why?
+- makes it easier to review in prs what is actually being produced
+  - e.g., visual spotcheck, make sure it looks good
+  - especially important when the output is userfacing (e.g., codegen, comms, etc)
+
+- makes it easier to detect exactly what the impact of a change is
+  - most of the time its intended and the snapshot can just be updated
+  - sometimes though, the snapshot diff exposes critical differences that are blockers or nitpicks that need to be addressed
+
+
+---
+
+critical:
+
+use both
+- a snapshot
+- AND
+- explicit assertions before the snapshot
+
+snapshot is for observability in code reviews and aesthetic verification
+assertions are for functional verification

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/.readme.md

@@ -0,0 +1 @@
+practices on which terms to use to promote a ubiquitous language go here

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/bad-practices/forbid.term=existing.md

@@ -0,0 +1,10 @@
+never use the term `existing`; its a needless gerund
+
+either
+- foundBefore
+- or
+- foundAfter
+
+or some nonGerund alternative
+
+but never `existing`

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/best-practice/require.order.noun_adj.md

@@ -0,0 +1,39 @@
+ always use [noun][adjective] order
+
+ e.g.,
+
+ instead of
+
+ currentOwner = [adj][noun]
+
+ prefer
+
+ ownerCurrent = [noun][adj]
+
+
+---
+
+instead of
+
+
+foundUser
+
+prefer
+
+userFound
+
+----
+
+
+why?
+
+because it enables autocomplete via common prefixes
+
+e.g.,
+
+userBefore
+userAfter
+userCreated
+etc
+
+can see via autocomplete suggestions all the variants of user available in the current scope, rather than need to remember what the variants are

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/domain=practices.terms=forbid_prefer_desire_require.md

@@ -0,0 +1,13 @@
+these are the terms we use to describe how to use practices
+
+forbid = search to ensure this was not done
+- it's a bad practice
+- it's a BLOCKER if detected
+
+prefer = search for opportunities to do this
+- it's a best practice, but not mandatory
+- it's a NITPICK if detected
+
+require = search for opportunities to do this
+- it's a best practice, and is mandatory
+- it's a BLOCKER if detected

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/domain=software.terms=prodcode_vs_testcode.md

@@ -0,0 +1,7 @@
+prodcode = the product's code
+- the code that produces the behavior users experience
+- the code that gets shipped to production
+
+testcode = the builder's code
+- the code that verifies the behaviors users experience
+- the code that runs at build time to protect production

package/dist/logic/roles/mechanic/.briefs/patterns/lang.tones/.readme.md

@@ -0,0 +1,3 @@
+briefs on what tones to use in writing goes here
+
+tones impact how things are thought about, so they are important to curate

package/dist/logic/roles/mechanic/.briefs/style.compressed.md

@@ -0,0 +1,29 @@
+// style:tactics (compressed)
+
+- name:ubiqlang
+  - use one canonical term per concept (e.g., always use `customer`, never `client`, `user`, or `account`)
+  - eliminate overloads: each term must refer to exactly one thing (e.g., do not use `update` for both "save" and "fetch")
+  - when introducing a new term:
+    - define its interface and role
+    - document its meaning clearly
+    - ensure consistent usage across code, docs, and tests
+
+- name:treestruct
+  - for mechanisms (procedures, steps, transforms), use `[Verb][NounHierarchy]` format
+    - verb must come first and be atomic (e.g., `gen`, `set`, `get`, `map`, `submit`)
+    - examples: `genStepImagineViaTemplate`, `setCustomerPhone`
+  - for resources (records, results), use `[NounHierarchy][State]?` format
+    - `State` is optional and should clarify the form or phase (e.g., `Found`, `Updated`, `Draft`, `Final`)
+    - examples: `contentFound`, `invoiceDraft`, `customer`
+  - group nouns by domain to maintain treesorted file and symbol organization
+
+- words:lowercase
+  - use lowercase for all non-code text (comments, prompts, markdown, logs)
+  - never capitalize:
+    - the start of a sentence
+    - generic nouns (`customer`, `step`)
+    - verbs (`set`, `submit`, `handle`)
+    - system messages or instructions
+  - only capitalize:
+    - code symbols (e.g., `StitchStepImagine`, `GitRepo`)
+    - proper nouns or brand names (e.g., OpenAI, GitHub)

package/dist/logic/roles/mechanic/.briefs/style.compressed.prompt.md

@@ -0,0 +1,5 @@
+compress these three style tactics for use in prompt context
+
+retain references to the tactics each section came from, so that it can always be dereferenced
+
+use outline form with each tactic a root bullet