@igorlau/dotagents 1.0.11 → 1.0.13
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 +2 -0
- package/content/skills/dot-implement/SKILL.md +52 -0
- package/content/skills/dot-implement/references/typescript.md +83 -0
- package/content/skills/dot-testing/SKILL.md +44 -0
- package/content/skills/dot-testing/references/typescript.md +64 -0
- package/dist/build-info.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -88,6 +88,8 @@ The following skills load when a task needs them:
|
|
|
88
88
|
| Skill | Purpose |
|
|
89
89
|
| ----- | ------- |
|
|
90
90
|
| `dot-plan` | Plan a change as small, verifiable steps. |
|
|
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. |
|
|
91
93
|
| `dot-code-review` | Review a diff for correctness bugs. |
|
|
92
94
|
| `dot-commit` | Commit changes as small, logical commits. |
|
|
93
95
|
| `dot-docs-writing` | Write docs in the Google developer documentation style. |
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dot-implement
|
|
3
|
+
description: Implement a feature, fix, refactor, or roadmap task to the repository's and the language's standards. Use when the user asks to build or change code, or to work a task from a dot-roadmap roadmap.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Implement
|
|
7
|
+
|
|
8
|
+
Turn a request, an approved plan, or a roadmap task into a working change that ends **green**: every check the work names passes, and you've shown the output.
|
|
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. Write code that fits those conventions.
|
|
13
|
+
|
|
14
|
+
## 1. Pin the work
|
|
15
|
+
|
|
16
|
+
Identify the source of the work:
|
|
17
|
+
|
|
18
|
+
- **Roadmap task**: a task file from `dot-roadmap`, or a roadmap directory. With only a directory, pick the lowest-id task whose blockers are all ticked in its `README.md`. If a named task has an unticked blocker, stop and name it. Read the task file and the roadmap's decisions in full. The task's "Out of scope" is a hard boundary.
|
|
19
|
+
- **Approved plan**: the plan in this conversation, from `dot-plan` or the user.
|
|
20
|
+
- **Request**: anything else.
|
|
21
|
+
|
|
22
|
+
Done when you can state the goal, the scope boundary, and the check that proves the work is done.
|
|
23
|
+
|
|
24
|
+
## 2. Plan when needed
|
|
25
|
+
|
|
26
|
+
A roadmap task or an approved plan is already the plan. For a request that touches more than one file, use the `dot-plan` skill and wait for the user's approval before you change any file. A single-file change goes straight to step 3.
|
|
27
|
+
|
|
28
|
+
## 3. Build
|
|
29
|
+
|
|
30
|
+
For each language the change touches, read its reference if one exists:
|
|
31
|
+
|
|
32
|
+
- [`references/typescript.md`](references/typescript.md): TypeScript and TSX.
|
|
33
|
+
|
|
34
|
+
When you write or change tests, use the `dot-testing` skill.
|
|
35
|
+
|
|
36
|
+
Work through the plan one step at a time, and run each step's check before you start the next one.
|
|
37
|
+
|
|
38
|
+
Done when every requirement of the task, plan, or request has code that meets it.
|
|
39
|
+
|
|
40
|
+
## 4. Verify
|
|
41
|
+
|
|
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.
|
|
43
|
+
|
|
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.
|
|
45
|
+
|
|
46
|
+
For a roadmap task, tick its checkbox in the roadmap's `README.md` once everything passes.
|
|
47
|
+
|
|
48
|
+
Done when the work is green.
|
|
49
|
+
|
|
50
|
+
## 5. Hand off
|
|
51
|
+
|
|
52
|
+
End with the verification output and anything you skipped or couldn't check. Suggest the `dot-code-review` skill for the diff, then the `dot-commit` skill. Leave the commit to the user.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# TypeScript reference
|
|
2
|
+
|
|
3
|
+
TypeScript rules for the [`dot-implement`](../SKILL.md) skill, based on the Google TypeScript style guide. They cover correctness, type safety, and API shape; leave formatting to the repository's formatter.
|
|
4
|
+
|
|
5
|
+
The repository's conventions and its compiler and linter configuration come first, then the always-on rules, then this reference. In a file that already breaks a rule, match the file for small changes instead of rewriting it, and keep style fixes out of a behavior change.
|
|
6
|
+
|
|
7
|
+
## Types
|
|
8
|
+
|
|
9
|
+
- Use `unknown` for values of unknown type, and narrow it with `typeof`, `instanceof`, `in`, or a type guard before use. Reach for `any` only where no type can express the value, such as a test mock, with a comment that says why.
|
|
10
|
+
- Validate data that crosses a trust boundary at the boundary: `JSON.parse` output, request bodies, environment variables, and file contents. Parse it into a typed value once, instead of casting.
|
|
11
|
+
- Prefer a runtime check to a type assertion (`as`) or a non-null assertion (`!`): both silence the compiler without checking anything. When an assertion is safe for a reason the code doesn't show, add a comment with the reason.
|
|
12
|
+
- Write assertions with `as`, never `<T>value`. When a double assertion is unavoidable, go through `unknown`.
|
|
13
|
+
- Annotate object literals with their type (`const foo: Foo = {...}`) or check them with `satisfies`, instead of asserting them with `as Foo`. An annotation catches misspelled and stale fields where the literal is declared.
|
|
14
|
+
- Fix compiler errors at their cause. Leave out `@ts-ignore`, `@ts-expect-error`, and `@ts-nocheck`; in a test that must pass an unchecked value, cast that one expression and comment why.
|
|
15
|
+
- Leave out annotations the compiler infers trivially, such as `const x = 5`. Annotate when inference would produce `unknown` or a wider type than intended, or when a complex return type is hard to read.
|
|
16
|
+
- Use interfaces for object types, and type aliases for unions, tuples, functions, and other non-object types.
|
|
17
|
+
- Declare a structural implementation's type where you create it (`const horse: Animal = {...}`), so a mismatch fails there instead of at a distant call site.
|
|
18
|
+
- Keep `| null` and `| undefined` out of type aliases. Add them where a value can actually be absent, and handle absence close to where it arises.
|
|
19
|
+
- Use optional fields and parameters (`name?: string`) instead of `name: string | undefined`.
|
|
20
|
+
- Use the lowercase primitive types: `string`, `number`, `boolean`, `object`. Use `unknown`, `object`, or `Record<string, T>` instead of `{}`.
|
|
21
|
+
- Write `T[]` and `readonly T[]` for simple element types, and `Array<T>` for complex ones.
|
|
22
|
+
- Use `Map` and `Set` for dictionaries with keys known only at runtime, and `Record<K, V>` for a fixed set of keys.
|
|
23
|
+
- Choose the simplest type that expresses the code. A few repeated properties or an interface that extends another beat a mapped or conditional type that readers must evaluate in their heads.
|
|
24
|
+
- Avoid generics that appear only in the return type. When an existing API has one, specify the type argument explicitly.
|
|
25
|
+
- Treat an indexed read from an array or a record as possibly `undefined`, and check it before use, even when `noUncheckedIndexedAccess` is off.
|
|
26
|
+
|
|
27
|
+
## Modules
|
|
28
|
+
|
|
29
|
+
- Use ES module syntax: `import` and `export`. Leave out `namespace`, `/// <reference>`, and `import x = require(...)`; use separate files to group code.
|
|
30
|
+
- Use named exports. Use a default import only for external code that requires it.
|
|
31
|
+
- Export only what other modules use. Use plain module-level functions and constants instead of classes that hold only static members.
|
|
32
|
+
- Keep exports immutable: never `export let`. Expose a mutable value through a getter function.
|
|
33
|
+
- Use `import type` for symbols used only as types, and `export type` to re-export types.
|
|
34
|
+
- Import project files with relative paths.
|
|
35
|
+
|
|
36
|
+
## Variables and data
|
|
37
|
+
|
|
38
|
+
- Declare with `const` by default and `let` when you reassign. Never use `var`. Declare one variable per statement, before its first use.
|
|
39
|
+
- Create arrays and objects with literals, not the `Array` or `Object` constructors.
|
|
40
|
+
- Spread only matching values: iterables into arrays, plain objects into objects. Never spread `null`, `undefined`, or primitives.
|
|
41
|
+
- Iterate arrays with `for...of`. Iterate objects with `Object.keys`, `Object.values`, or `Object.entries`; a `for...in` loop also visits inherited properties.
|
|
42
|
+
- Keep parameter destructuring to one level of shorthand properties, with defaults on the left side.
|
|
43
|
+
- Parse numbers with `Number()` and check the result for `NaN`. Use `parseInt` only for a radix other than 10, after checking the digits. Never coerce with unary `+`.
|
|
44
|
+
- Coerce with `String()`, `Boolean()`, or a template literal, never with the wrapper constructors (`new String()`).
|
|
45
|
+
- Compare enum values explicitly, never by truthiness: the first member is `0`, which is falsy.
|
|
46
|
+
- Use `===` and `!==`. The one exception is `== null`, which matches both `null` and `undefined`.
|
|
47
|
+
|
|
48
|
+
## Functions and classes
|
|
49
|
+
|
|
50
|
+
- Use function declarations for named functions, and arrow functions for callbacks and nested functions. Leave out function expressions.
|
|
51
|
+
- Pass an arrow function that forwards its arguments (`items.map((item) => parse(item))`) rather than a named function (`items.map(parse)`): the callee might pass extra arguments that the named function accepts with a different meaning.
|
|
52
|
+
- Give an arrow function a block body when its return value is unused.
|
|
53
|
+
- Use `this` only in constructors, methods, and arrow functions inside them. Never use it in a static context.
|
|
54
|
+
- Use rest parameters and spread instead of `arguments` and `Function.prototype.apply`.
|
|
55
|
+
- Keep default parameter values free of side effects.
|
|
56
|
+
- Mark properties that are never reassigned after the constructor `readonly`. Use parameter properties instead of copying constructor arguments by hand.
|
|
57
|
+
- Initialize every class property in its declaration or the constructor, including optional ones as `undefined`, so the object's shape never changes.
|
|
58
|
+
- Keep visibility as narrow as possible. Prefer a module-level function to a private method. Leave out the `public` modifier except on a mutable parameter property, and never use `obj['name']` to get around `private`.
|
|
59
|
+
- Keep getters free of side effects, and skip accessors that only pass a property through.
|
|
60
|
+
- Leave prototypes and built-in objects unmodified.
|
|
61
|
+
|
|
62
|
+
## Control flow and errors
|
|
63
|
+
|
|
64
|
+
- Wrap every `if`, `for`, and `while` body in braces; only an `if` that fits on one line may skip them. Keep assignments out of conditions.
|
|
65
|
+
- Give every `switch` a final `default` group, and end every non-empty `case` with `break`, `return`, or `throw`. When a `switch` covers every member of a union or an enum, make `default` assign the value to a `never` variable, so adding a member fails the type check.
|
|
66
|
+
- Throw only `Error` objects or subclasses, created with `new`, and reject promises only with `Error`s. Prefer throwing to returning error objects.
|
|
67
|
+
- Treat a caught value as an `Error`, and skip defensive handling of non-`Error` throws unless a dependency actually throws them.
|
|
68
|
+
- Handle a caught error or comment why ignoring it is correct; never leave a `catch` block empty and silent.
|
|
69
|
+
- Keep a `try` block to the statements that can throw.
|
|
70
|
+
- Await every promise, return it, or handle its rejection. A promise left floating loses its errors; when fire-and-forget is intended, mark it with `void` and attach a `.catch`.
|
|
71
|
+
|
|
72
|
+
## Language features to avoid
|
|
73
|
+
|
|
74
|
+
- `const enum` (use a plain `enum` or a union of literals), `with`, `eval`, the `Function(string)` constructor, and `debugger` in committed code.
|
|
75
|
+
- Semicolon-free code that relies on automatic semicolon insertion.
|
|
76
|
+
- Non-standard and proposal-stage JavaScript features, unless the project targets a runtime that ships them.
|
|
77
|
+
- New decorators. Use the decorators a framework defines, placed directly before the symbol they decorate.
|
|
78
|
+
|
|
79
|
+
## Naming
|
|
80
|
+
|
|
81
|
+
- Use `UpperCamelCase` for classes, interfaces, types, enums, and type parameters; `lowerCamelCase` for variables, functions, methods, and properties; and `CONSTANT_CASE` for module-level constants and enum members.
|
|
82
|
+
- Write descriptive names without abbreviations a new reader wouldn't know. Leave type information out of names: no `I` prefix on interfaces, no Hungarian notation, and no `_` prefix or suffix for private members.
|
|
83
|
+
- Mark deprecated APIs with `@deprecated` and directions for migrating call sites.
|
|
@@ -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.
|
package/dist/build-info.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"commit":"
|
|
1
|
+
{"commit":"3187ce7"}
|