@igorlau/dotagents 1.0.12 → 1.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -89,6 +89,7 @@ The following skills load when a task needs them:
89
89
  | ----- | ------- |
90
90
  | `dot-plan` | Plan a change as small, verifiable steps. |
91
91
  | `dot-implement` | Implement a change or roadmap task to the repository's and language's standards. |
92
+ | `dot-testing` | Write tests around a shared makeSut factory. |
92
93
  | `dot-code-review` | Review a diff for correctness bugs. |
93
94
  | `dot-commit` | Commit changes as small, logical commits. |
94
95
  | `dot-docs-writing` | Write docs in the Google developer documentation style. |
@@ -2,12 +2,14 @@
2
2
 
3
3
  Apply these rules when you write, refactor, or review code:
4
4
 
5
- - Comment the why that the code can't show: a constraint, a workaround with its issue link, a non-obvious trade-off, an invariant, or the source of copied code. Keep it to one line when you can.
6
- - Let the code carry the what. When a comment would restate the code, improve a name or extract a function instead, and write no comment.
5
+ - Leave most code without comments. Comment the why the code can't show: a constraint, a workaround with its issue link, a non-obvious trade-off, an invariant, or the source of copied code. Keep it to one line when you can.
6
+ - Let names and types carry the what. When a comment would restate the code, improve a name or extract a function instead.
7
+ - Assume the reader knows the language, its libraries, and the platform. Comment only what is specific to this code.
7
8
  - Write comments for future readers of the code as it is. Change history, notes such as "added" or "now uses", and messages to the reviewer belong in the commit message or pull request.
8
9
  - Delete code instead of commenting it out. Git keeps the history.
9
- - Document public APIs in the language's doc-comment convention: purpose, contract, errors, and side effects, not the implementation.
10
+ - Write doc comments where the repository documents its APIs, or on an exported API whose name and types don't show its contract. Cover purpose, contract, errors, and side effects, not the implementation.
11
+ - Write comments above a function, class, property, or other declaration as doc comments in the language's convention, such as `/** */` JSDoc in TypeScript, so editors show them in hover tooltips, unless the surrounding code uses another style.
10
12
  - Explain regular expressions and complex algorithms with what they match or compute.
11
13
  - When you change code, update every comment that the change makes inaccurate, and delete comments that no longer apply.
12
14
  - When you review code, flag comments that restate the code, contradict it, or narrate changes, and ask for a why comment where intentional code looks wrong.
13
- - Match the comment density and style of the surrounding code.
15
+ - Match the comment density and style of the surrounding code. In a new file, match the repository's other files.
@@ -31,13 +31,15 @@ For each language the change touches, read its reference if one exists:
31
31
 
32
32
  - [`references/typescript.md`](references/typescript.md): TypeScript and TSX.
33
33
 
34
+ When you write or change tests, use the `dot-testing` skill.
35
+
34
36
  Work through the plan one step at a time, and run each step's check before you start the next one.
35
37
 
36
38
  Done when every requirement of the task, plan, or request has code that meets it.
37
39
 
38
40
  ## 4. Verify
39
41
 
40
- Run the task's "Verify" section, the plan's final check, or the repository's tests, type checker, and linter, and show the output. Check every acceptance criterion one by one.
42
+ Run the task's "Verify" section, the plan's final check, or the repository's tests, type checker, and linter, and show the output. Check every acceptance criterion one by one. Reread your diff against the code comments rule, and fix what it flags.
41
43
 
42
44
  When verification fails, or the task or plan turns out wrong (a fact contradicts it, or meeting it needs work outside its scope), stop. Report the failing check or the conflicting fact and propose a change to the task or plan. Keep the task file, the roadmap's decisions, and the plan as they are until the user agrees, and keep the change inside its scope.
43
45
 
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: dot-testing
3
+ description: Write and change tests with a makeSut factory per suite. Use when adding, fixing, or restructuring tests, unit or integration.
4
+ ---
5
+
6
+ # Testing
7
+
8
+ Write tests that build the **system under test** (`sut`) in one factory, share it across the suite, and stay isolated by resetting the test doubles between tests.
9
+
10
+ ## Repository conventions first
11
+
12
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. When the repository already sets up tests another way, such as pytest fixtures or its own setup helper, use that and leave out `makeSut`.
13
+
14
+ ## The makeSut factory
15
+
16
+ Use `makeSut` when the subject needs setup: construction, configuration, dependencies, or a resource such as a database or a server. Call a subject without setup directly in its own `describe`: pure functions, utilities, and constants. The test is "does it need setup?", not "is it a utility?"; a utility that takes an injected clock gets a `makeSut`.
17
+
18
+ - Name it in the language's casing (`makeSut`, `make_sut`), and always call the tested object `sut`.
19
+ - Give it no parameters. It returns an object with `sut`, every test double by name, and `cleanup` when a resource needs releasing: `{ sut, repositoryStub, cleanup }`. When setup fails partway, it releases what it already opened before rethrowing.
20
+ - Build each test double in its own factory (`makeRepositoryStub()`) whose methods return the happy path, so a test spells out only what differs.
21
+ - Place `makeSut` and the double factories in the test file, after the imports. Move them to a shared helper once a second test file needs them.
22
+
23
+ ## Suite lifecycle
24
+
25
+ 1. Call `makeSut` once per top-level `describe`, in the hook that runs before all tests, and call `cleanup` in the hook that runs after all of them.
26
+ 2. In a test, change a dependency's behavior by spying on or stubbing the double that `makeSut` returned, for that test only.
27
+ 3. Restore every spy and stub in the hook that runs after each test, so the next test sees the happy-path doubles again.
28
+
29
+ When the `sut` itself keeps mutable state between calls (an in-memory cache, a counter, a queue), resetting the doubles leaves that state behind. Give that `describe` its own `makeSut` call before each test and `cleanup` after each test, with a comment that names the state. Tests that run concurrently share the doubles the same way, so in a concurrent suite each test calls `makeSut` itself, calls `cleanup` when it ends, and drops the shared restore hook: a global restore undoes the spies of tests still running, and each test's doubles die with it.
30
+
31
+ ## Test principles
32
+
33
+ - Arrange, act, assert: one block each, in that order.
34
+ - Test one behavior per test, and name the test after that behavior ("returns null when the user is missing").
35
+ - Assert on outputs and on calls that cross the `sut`'s boundary, not on its private steps.
36
+ - Prefer stubs and fakes that return data to mocks that assert the call sequence.
37
+
38
+ ## Language references
39
+
40
+ Read the reference for each language the tests use, if one exists:
41
+
42
+ - [`references/typescript.md`](references/typescript.md): TypeScript with Vitest, Jest, or `node:test`.
43
+
44
+ Done when every test you wrote or changed passes with the repository's test command, and you've shown the output.
@@ -0,0 +1,64 @@
1
+ # TypeScript reference
2
+
3
+ TypeScript details for the [`dot-testing`](../SKILL.md) skill. Use the runner the repository already has.
4
+
5
+ ## Hooks by runner
6
+
7
+ | Step | Vitest and Jest | `node:test` |
8
+ | ---- | --------------- | ----------- |
9
+ | Build the suite | `beforeAll` | `before` |
10
+ | Release it | `afterAll` | `after` |
11
+ | Restore the doubles | `afterEach(() => vi.restoreAllMocks())` or `jest.restoreAllMocks()` | `afterEach(() => mock.restoreAll())` |
12
+
13
+ Write the doubles as plain objects with happy-path methods, not `jest.fn(impl)` or `vi.fn(impl)`: in Jest 29 and earlier, restoring or resetting mocks erases `impl`, which the next tests still need. Override a method per test with `vi.spyOn`, `jest.spyOn`, or `mock.method`, and restoring puts back the happy path.
14
+
15
+ ## Example
16
+
17
+ ```ts
18
+ import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
19
+ import { type UserRepository, UserService } from "../src/user-service.ts";
20
+
21
+ function makeRepositoryStub(): UserRepository {
22
+ return {
23
+ async findById(id) {
24
+ return { id, name: "Ada" };
25
+ },
26
+ };
27
+ }
28
+
29
+ function makeSut() {
30
+ const repositoryStub = makeRepositoryStub();
31
+ const sut = new UserService(repositoryStub);
32
+ return { sut, repositoryStub };
33
+ }
34
+
35
+ describe("UserService", () => {
36
+ let suite: ReturnType<typeof makeSut>;
37
+
38
+ beforeAll(() => {
39
+ suite = makeSut();
40
+ });
41
+ afterEach(() => {
42
+ vi.restoreAllMocks();
43
+ });
44
+
45
+ it("returns the user's display name", async () => {
46
+ const { sut } = suite;
47
+
48
+ const name = await sut.displayName("1");
49
+
50
+ expect(name).toBe("Ada");
51
+ });
52
+
53
+ it("returns null when the user is missing", async () => {
54
+ const { sut, repositoryStub } = suite;
55
+ vi.spyOn(repositoryStub, "findById").mockResolvedValueOnce(null);
56
+
57
+ const name = await sut.displayName("1");
58
+
59
+ expect(name).toBeNull();
60
+ });
61
+ });
62
+ ```
63
+
64
+ For a resource, return `cleanup` from `makeSut` and call it in `afterAll(() => suite?.cleanup())`: `suite` is unset when `makeSut` throws.
@@ -1 +1 @@
1
- {"commit":"e82bea2"}
1
+ {"commit":"f6ee8bc"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@igorlau/dotagents",
3
- "version": "1.0.12",
3
+ "version": "1.0.14",
4
4
  "description": "Install a curated set of agent skills and rules into Claude Code, Codex, and GitHub Copilot.",
5
5
  "license": "MIT",
6
6
  "repository": {