rhachet-roles-ehmpathy 1.17.19 → 1.17.21

package/dist/domain.roles/mechanic/briefs/practices/code.test/scope.unit/rule.forbid.remote-boundaries.md

@@ -0,0 +1,153 @@
+# rule.forbid.remote-boundaries
+
+## .what
+
+unit tests must not cross remote boundaries — if a test touches external resources, it is an integration test, not a unit test
+
+## .why
+
+- **unit tests verify atomic logic** — pure functions with injected dependencies
+- **remote boundaries introduce flake** — network timeouts, file locks, db state
+- **remote boundaries introduce latency** — disk i/o, connection overhead, query time
+- **remote boundaries hide in mocks** — mocks create false confidence; the mock behaves differently than reality
+- **test classification matters** — `npm run test:unit` must be fast, deterministic, and parallelizable
+
+## .scope
+
+applies to all files with `.test.ts` extension (unit tests)
+
+does NOT apply to `.integration.test.ts` or `.acceptance.test.ts`
+
+## .remote boundaries
+
+a remote boundary is any resource external to the process memory:
+
+| boundary   | examples                                                      | why it's remote                                    |
+| ---------- | ------------------------------------------------------------- | -------------------------------------------------- |
+| filesystem | `fs.readFile`, `fs.writeFile`, `path.resolve` with real paths | disk i/o, file locks, path differences across os   |
+| database   | `pg.query`, `mysql.execute`, dao calls                        | connection state, query latency, data dependencies |
+| network    | `fetch`, `axios`, http clients, sdk calls                     | latency, availability, rate limits                 |
+
+## .how
+
+### 👍 unit test — pure logic leaf
+
+```ts
+// computeInvoiceTotal.test.ts
+describe('computeInvoiceTotal', () => {
+  it('sums line items correctly', () => {
+    const result = computeInvoiceTotal({
+      lineItems: [
+        { amount: 100 },
+        { amount: 50 },
+      ],
+    });
+    expect(result).toEqual(150);
+  });
+});
+```
+
+### 👍 unit test — dependency injection enables isolation
+
+```ts
+// sendInvoice.test.ts
+describe('sendInvoice', () => {
+  it('returns sent status when email succeeds', async () => {
+    // inject a fake, not a mock of a real service
+    const svcEmailDemo = {
+      send: async () => ({ success: true }),
+    };
+
+    const result = await sendInvoice(
+      { invoice: exampleInvoice }, // input stays pure as always
+      { svcEmail: svcEmailDemo }, // context has remote interfaces injected; makes it clear that _any_ shape that fits this contract is allowed
+    );
+
+    expect(result.sent).toEqual(true);
+  });
+});
+```
+
+### 👎 bad — crosses filesystem boundary
+
+```ts
+// ❌ this is an integration test, not a unit test
+describe('loadConfig', () => {
+  it('reads config from disk', async () => {
+    const config = await loadConfig({ path: './config.json' }); // fs access
+    expect(config.apiKey).toBeDefined();
+  });
+});
+```
+
+### 👎 bad — crosses database boundary
+
+```ts
+// ❌ this is an integration test, not a unit test
+describe('getUserById', () => {
+  it('fetches user from database', async () => {
+    const user = await getUserById({ id: '123' }, { dbConnection }); // db access
+    expect(user.name).toEqual('alice');
+  });
+});
+```
+
+### 👎 bad — mocks hide the boundary (antipattern)
+
+```ts
+// ❌ mocks are an antipattern — they create false confidence
+jest.mock('fs');
+const fs = require('fs');
+
+describe('loadConfig', () => {
+  it('reads config', async () => {
+    fs.readFile.mockResolvedValue('{"key": "value"}');
+    const config = await loadConfig({ path: './config.json' });
+    expect(config.key).toEqual('value');
+    // 👎 this test passes but real fs.readFile behaves differently
+    // 👎 the mock doesn't validate encode, error handler, path resolution
+  });
+});
+```
+
+## .what to do instead
+
+| if your test needs... | then...                        |
+| --------------------- | ------------------------------ |
+| filesystem access     | move to `.integration.test.ts` |
+| database queries      | move to `.integration.test.ts` |
+| network calls         | move to `.integration.test.ts` |
+
+## .the mock antipattern
+
+mocks are forbidden because:
+
+1. **mocks lie** — they return what you tell them, not what the real dependency returns
+2. **mocks drift** — when the real dependency changes, the mock doesn't
+3. **mocks hide bugs** — the test passes but production fails
+4. **mocks test the mock** — you verify your mock setup, not your logic
+
+### instead of mocks, use:
+
+- **fakes** — simplified implementations that behave like the real dependency
+- **dependency injection** — pass the dependency as a parameter
+- **integration tests** — test the real dependency in `.integration.test.ts`
+
+## .classification guide
+
+| test characteristics                   | classification | file extension         |
+| -------------------------------------- | -------------- | ---------------------- |
+| pure logic, no i/o, injected deps      | unit           | `.test.ts`             |
+| touches db, fs, network                | integration    | `.integration.test.ts` |
+| blackbox via built artifact's contract | acceptance     | `.acceptance.test.ts`  |
+
+## .enforcement
+
+unit test that crosses remote boundary = **BLOCKER**
+
+mock usage in unit tests = **BLOCKER**
+
+---
+
+> unit tests are fast, deterministic, and test logic in isolation.
+> if it touches the outside world, it's not a unit test.

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.17.19",
+  "version": "1.17.21",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [
@@ -16,7 +16,8 @@
     "node": ">=8.0.0"
   },
   "files": [
-    "/dist"
+    "/dist",
+    "rhachet.repo.yml"
   ],
   "scripts": {
     "build:ts": "tsc -p ./tsconfig.build.json",
@@ -27,7 +28,9 @@
     "fix": "npm run fix:format && npm run fix:lint",
     "build:clean": "chmod -R u+w dist 2>/dev/null; rm -rf dist/",
     "build:compile": "tsc -p ./tsconfig.build.json && tsc-alias -p ./tsconfig.build.json",
-    "build:complete": "rsync -a --prune-empty-dirs --include='*/' --exclude='**/.route/**' --exclude='**/.scratch/**' --exclude='**/.behavior/**' --exclude='**/*.test.sh' --include='**/readme.md' --include='**/*.template.md' --include='**/briefs/**/*.md' --include='**/briefs/*.md' --include='**/skills/**/*.sh' --include='**/skills/*.sh' --include='**/skills/**/*.jsonc' --include='**/skills/*.jsonc' --include='**/inits/**/*.sh' --include='**/inits/*.sh' --include='**/inits/**/*.jsonc' --include='**/inits/*.jsonc' --exclude='*' src/ dist/",
+    "build:complete:dist": "rsync -a --prune-empty-dirs --include='*/' --exclude='**/.route/**' --exclude='**/.scratch/**' --exclude='**/.behavior/**' --exclude='**/*.test.sh' --include='**/readme.md' --include='**/*.template.md' --include='**/briefs/**/*.md' --include='**/briefs/*.md' --include='**/skills/**/*.sh' --include='**/skills/*.sh' --include='**/skills/**/*.jsonc' --include='**/skills/*.jsonc' --include='**/inits/**/*.sh' --include='**/inits/*.sh' --include='**/inits/**/*.jsonc' --include='**/inits/*.jsonc' --exclude='*' src/ dist/",
+    "build:complete:repo": "npx rhachet repo introspect",
+    "build:complete": "npm run build:complete:dist && npm run build:complete:repo",
     "build": "npm run build:clean && npm run build:compile && npm run build:complete --if-present",
     "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
     "test:types": "tsc -p ./tsconfig.json --noEmit",
@@ -89,10 +92,10 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.21.5",
-    "rhachet-roles-bhrain": "0.5.9",
-    "rhachet-roles-bhuild": "0.6.4",
-    "rhachet-roles-ehmpathy": "link:.",
+    "rhachet": "1.22.7",
+    "rhachet-roles-bhrain": "0.5.11",
+    "rhachet-roles-bhuild": "0.6.6",
+    "rhachet-roles-ehmpathy": "1.17.20",
     "test-fns": "1.6.0",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",

package/rhachet.repo.yml

@@ -0,0 +1,19 @@
+slug: ehmpathy
+readme: dist/domain.roles/readme.md
+roles:
+  - slug: architect
+    readme: dist/domain.roles/architect/readme.md
+    briefs:
+      dirs: dist/domain.roles/architect/briefs
+    skills:
+      dirs: []
+  - slug: mechanic
+    readme: dist/domain.roles/mechanic/readme.md
+    briefs:
+      dirs: dist/domain.roles/mechanic/briefs
+    skills:
+      dirs: dist/domain.roles/mechanic/skills
+    inits:
+      dirs: dist/domain.roles/mechanic/inits
+      exec:
+        - dist/domain.roles/mechanic/inits/init.claude.sh