@staff0rd/assist 0.139.0 → 0.140.1

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:*)"]

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@staff0rd/assist",
-  version: "0.139.0",
+  version: "0.140.1",
   type: "module",
   main: "dist/index.js",
   bin: {
@@ -63,6 +63,7 @@ var package_default = {
     "@types/react-dom": "^19.2.3",
     "@types/semver": "^7.7.1",
     "@types/shell-quote": "^1.7.5",
+    "@vitest/coverage-v8": "^4.1.2",
     esbuild: "^0.27.3",
     jotai: "^2.18.0",
     jscpd: "^4.0.5",
@@ -2818,6 +2819,14 @@ async function run2(id) {
   if (!plan2) return;
   setStatus(id, "in-progress");
   const startPhase = item.currentPhase ?? 0;
+  if (startPhase >= plan2.length) {
+    setStatus(id, "done");
+    console.log(
+      chalk35.green(`All phases already complete for #${id}: ${item.name}`)
+    );
+    console.log(chalk35.dim("Review the changes, then use /commit when ready."));
+    return;
+  }
   console.log(chalk35.bold(`Running plan for #${id}: ${item.name}`));
   if (startPhase > 0) {
     console.log(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@staff0rd/assist",
-	"version": "0.139.0",
+	"version": "0.140.1",
 	"type": "module",
 	"main": "dist/index.js",
 	"bin": {
@@ -57,6 +57,7 @@
 		"@types/react-dom": "^19.2.3",
 		"@types/semver": "^7.7.1",
 		"@types/shell-quote": "^1.7.5",
+		"@vitest/coverage-v8": "^4.1.2",
 		"esbuild": "^0.27.3",
 		"jotai": "^2.18.0",
 		"jscpd": "^4.0.5",