@staff0rd/assist 0.138.0 → 0.140.0

package/README.md

@@ -45,6 +45,8 @@ After installation, the `assist` command will be available globally. You can als
 - `/journal` - Append a journal entry summarising recent work, decisions, and notable observations
 - `/standup` - Summarise recent journal entries as a standup update
 - `/sync` - Sync commands and settings to ~/.claude
+- `/test-cover` - Incrementally increase test coverage by identifying and testing uncovered files
+- `/test-review` - Review existing tests for quality, coverage gaps, and adherence to conventions
 - `/inspect` - Run .NET code inspections on changed files
 - `/screenshot` - Capture a screenshot of a running application window
 - `/seq` - Query Seq logs from a URL or filter expression

package/claude/CLAUDE.md

@@ -5,7 +5,9 @@ The tool is invoked using the `assist` command and is installed globally. Use it
 When renaming TypeScript files or symbols, use the refactor commands instead of doing it manually:
 - `assist refactor rename file <source> <destination>` — rename/move a file and update all imports
 - `assist refactor rename symbol <file> <oldName> <newName>` — rename a variable, function, class, or type across the project
-Both default to dry-run; add `--apply` to execute.
+- `assist refactor extract <file> <functionName> <destination>` — extract a function and its private dependencies to a new file
+All default to dry-run; add `--apply` to execute.
+When using extract, name the destination file after the exported function (e.g. `updateWorkerCapacity.ts` for `updateWorkerCapacity`) to satisfy `useFilenamingConvention` lint rules.
 
 When the user mentions a Jira issue key (e.g. `BAD-671`, `PROJ-123`), use these commands to fetch context:
 - `assist jira view <issue-key>` — print the title and description

package/claude/commands/commit.md

@@ -15,3 +15,4 @@ Where:
 - Any subsequent arguments are paths to git add before committing
 - The commit message is 40 characters or less
 - The commit message does not reference Claude
+- Match the repo's commit message style (check git log). If the repo uses conventional commits, ensure the prefix accurately reflects the nature of the change (e.g. don't use `feat:` for non-functional changes like backlog updates or config)

package/claude/commands/test-cover.md

@@ -0,0 +1,119 @@
+---
+description: Incrementally increase test coverage by identifying and testing uncovered files
+allowed_args: "[number of files to cover, default 1]"
+---
+
+You are increasing test coverage for this project. Your goal is to pick the highest-value uncovered file(s) and write thorough tests for them.
+
+## Step 1: Measure current coverage
+
+Run coverage against all source files to identify what is untested:
+
+```
+npx vitest run --coverage --coverage.include='src/**/*.ts' --coverage.all --coverage.reporter=json 2>&1
+```
+
+Read the JSON coverage report at `coverage/coverage-final.json` to get per-file statement coverage percentages. Identify files with 0% or low coverage.
+
+## Step 2: Prioritise files
+
+From the uncovered files, prioritise by:
+
+1. **Pure logic** — functions with clear inputs/outputs, no side effects (parsers, validators, transformers)
+2. **Shared utilities** — files under `src/shared/` used by multiple consumers
+3. **Complexity** — files with branching logic, edge cases, or error handling
+
+Skip files that are primarily:
+- Thin CLI wrappers (just parse args and call another function)
+- UI components (React/TSX)
+- Files that only re-export or wire things together
+
+Select the number of files specified by `$ARGUMENTS` (default: 1).
+
+## Step 3: Read the source and existing tests
+
+Read each selected source file thoroughly. Also read any existing test files nearby to understand the project's testing patterns.
+
+## Step 4: Write tests
+
+Create a test file colocated with the source file, named `<source>.test.ts`.
+
+Follow these conventions exactly:
+
+- Import from `vitest`: `import { describe, expect, it } from "vitest";` (add `vi` only if mocking)
+- Use Vitest's native `expect()` — no external assertion libraries
+- Define helper functions locally in the test file when needed (e.g., factory functions for test data)
+- Mock dependencies with `vi.mock()` only when necessary — prefer real implementations
+
+### BDD structure
+
+Use a behavioural, BDD-style structure:
+
+- **Outer `describe`** — the function or module under test
+- **Inner `describe("when ...")`** — groups tests that share the same setup/scenario
+- **`it("should ...")`** — asserts a single rule or behaviour
+
+Each test follows an **Arrange, Act, Assert** pattern. Do NOT add `// arrange`, `// act`, `// assert` comments — just structure the code in that order with whitespace separating the three sections.
+
+Keep assertions per test to a minimum — ideally one, at most two closely related assertions. If you need to assert multiple things about the same action, split them into separate `it` blocks under the same `describe("when ...")`.
+
+Example:
+
+```typescript
+describe("parseToken", () => {
+  describe("when given a valid token", () => {
+    it("should return the decoded payload", () => {
+      const token = createToken({ sub: "user-1" });
+
+      const result = parseToken(token);
+
+      expect(result.sub).toBe("user-1");
+    });
+  });
+
+  describe("when given an expired token", () => {
+    it("should throw an expiration error", () => {
+      const token = createToken({ exp: pastDate() });
+
+      expect(() => parseToken(token)).toThrow("expired");
+    });
+  });
+});
+```
+
+### Coverage targets
+
+Cover:
+- Happy path for each exported function
+- Edge cases (empty input, undefined, boundary values)
+- Error cases and invalid input
+- Branch coverage — ensure each conditional path is exercised
+
+## Step 5: Run and verify
+
+Run the tests to confirm they pass:
+
+```
+npx vitest run <test-file-path> 2>&1
+```
+
+If any tests fail, fix them. Then re-run coverage to confirm the file now has >90% statement coverage:
+
+```
+npx vitest run --coverage --coverage.include='<source-file-path>' 2>&1
+```
+
+## Step 6: Run /verify
+
+Run `/verify` to ensure nothing is broken.
+
+## Step 7: Report
+
+Show a before/after summary:
+
+```
+File                    | Before | After
+<file path>             | 0%     | 95%
+```
+
+And the new repo-wide coverage number.

package/claude/commands/test-review.md

@@ -0,0 +1,75 @@
+---
+description: Review existing tests for quality, coverage gaps, and adherence to conventions
+allowed_args: "[file or directory path to review, default: all test files]"
+---
+
+You are reviewing existing tests for quality. Your goal is to identify tests that are weak, misleading, or missing important coverage — and to recommend specific improvements.
+
+## Step 1: Find test files
+
+If `$ARGUMENTS` specifies a path, scope to that. Otherwise, find all `*.test.ts` files under `src/`.
+
+## Step 2: Read each test file and its source
+
+For each test file, read both the test and the source file it covers. You need both to judge whether the tests are adequate.
+
+## Step 3: Evaluate each test file
+
+Assess each test file against these criteria:
+
+### Correctness
+- Do assertions actually verify the behaviour, or are they tautological (e.g., testing that a mock returns what you told it to)?
+- Are expected values correct and meaningful, not just copied from implementation output?
+- Do tests assert the right thing — return values, side effects, thrown errors — for each scenario?
+
+### Coverage of behaviour
+- Are all exported functions tested?
+- Are conditional branches exercised (if/else, switch, early returns, error paths)?
+- Are edge cases covered (empty input, null/undefined, boundary values, large input)?
+- Are error cases tested (invalid arguments, missing data, thrown exceptions)?
+
+### Test independence
+- Can each test run in isolation, or do tests depend on shared mutable state or execution order?
+- Are mocks reset properly between tests?
+
+### BDD structure and Arrange-Act-Assert
+- Does the outer `describe` name the function or module under test?
+- Do inner `describe("when ...")` blocks group tests by shared setup/scenario?
+- Do `it` blocks use `should` phrasing (e.g., `it("should return empty array when no matches")`)?
+- Does each test follow Arrange, Act, Assert ordering (without comments labelling the sections)?
+- Are assertions minimal per test — ideally one, at most two closely related? If multiple things are asserted about the same action, are they split into separate `it` blocks under the same `describe("when ...")`?
+
+### Mocking discipline
+- Are mocks used only when necessary (external I/O, complex dependencies)?
+- Do mocks faithfully represent the real dependency's contract, or do they mask bugs?
+- Is there a risk that mocked tests pass but real integration would fail?
+
+### Missing tests
+- Are there exported functions or significant code paths with no corresponding test?
+- Are there recently added functions (check git log) that lack tests?
+
+## Step 4: Report findings
+
+For each test file, report:
+
+**File:** `path/to/file.test.ts`
+
+**Verdict:** Good / Needs improvement / Weak
+
+**Strengths:**
+- (what the tests do well)
+
+**Issues:**
+- (specific problems, each with a concrete recommendation)
+
+**Missing coverage:**
+- (untested functions or paths, with suggested test cases)
+
+## Step 5: Summary
+
+End with an overall summary:
+
+- Total test files reviewed
+- Breakdown by verdict (Good / Needs improvement / Weak)
+- Top 3 highest-priority improvements across all files
+- Whether any tests risk giving false confidence (passing despite bugs)

package/claude/settings.json

@@ -89,6 +89,10 @@
 			"SlashCommand(/screenshot)",
 			"Skill(draft)",
 			"SlashCommand(/draft)",
+			"Skill(test-cover)",
+			"SlashCommand(/test-cover)",
+			"Skill(test-review)",
+			"SlashCommand(/test-review)",
 			"WebFetch(domain:staffordwilliams.com)"
 		],
 		"deny": ["Bash(git commit:*)", "Bash(npm run:*)", "Bash(npx assist:*)"]