Validation tests

[jonathanKingston]

We should add some more verification tests that prevent regressions.

[jonathanKingston]

@cursor please look at the codebase and create a detailed plan for implementing this. Don't make changes yet, just outline the approach, which files need changing, and any trade-offs.

[cursor]

Now I have a thorough understanding of the codebase. Here's my detailed plan:

---

Validation Tests Plan for Copse CLI

Current State

• 1 test file exists: tests/filters.test.ts (5 tests covering filterPRsByAuthor, filterPRsByAgent, filterPRs, buildFetchMessage)
• CI does not run unit tests — only type check, build, and --help smoke tests
• Test framework: Node built-in node:test + node:assert/strict
• Test runner: node --test "dist/tests/**/*.test.js" (compiles first via pretest)

Proposed New Test Files

1. tests/gh-validation.test.ts — Validation functions in lib/gh.ts

What to test:

Function	Test Cases
validateRepo	Valid owner/name, dots/hyphens/underscores allowed, rejects empty string, rejects bare name, rejects triple-segment a/b/c, rejects special chars (@, spaces)
validateAgent	Accepts "cursor", "claude", "copilot", normalizes case ("Cursor" → "cursor"), rejects unknown agents ("gemini"), rejects empty string
matchesAgent	Branch match (cursor/fix-bug), label match (cursor-pr), case-insensitive, no match on unrelated branch/label, null agent matches any known agent, unknown agent pattern returns false
getAgentForPR	Returns first matching agent name, returns bot agent for dependabot PRs, returns null for unmatched PRs
isBotPR / getBotAgent	Identifies app/dependabot, returns null for normal users, handles missing author.login
formatGhError	Extracts stderr, falls back to message, includes context prefix, handles empty/missing fields

Approach: All pure functions, no mocking needed. Import directly and test with makePR-style fixtures (same pattern as existing filters.test.ts).

File changes: New file tests/gh-validation.test.ts. Will need to export REPO_PATTERN (already exported).

2. tests/args.test.ts — Argument parsing in lib/args.ts

What to test:

Function	Test Cases
parseStandardFlags	--dry-run sets flag, --all sets all: true and mineOnly: false, --mine is stripped but mineOnly defaults to true, multiple flags together, no flags gives defaults, flags removed from filtered output
parseHoursOption	Valid number, missing value throws, 0 throws (must be positive), negative throws, non-numeric throws
parseBaseOption	Valid value, missing value throws
parseTemplateOption	Valid value, missing value throws
calculateSinceDate	Returns date N hours ago (within tolerance), 1 hour, 48 hours

Approach: Pure functions, no external deps. Straightforward assertions.

File changes: New file tests/args.test.ts.

3. tests/config.test.ts — Config loading in lib/config.ts

What to test:

Function	Test Cases
loadConfig	Valid .copserc with repos array, invalid JSON returns null, missing repos key returns null, repos not an array returns null, repos with non-string elements returns null, empty repos array returns valid config, no .copserc returns null
getConfiguredRepos	Returns repos from valid config, returns null for empty repos, returns null when no config

Approach: Create temp directories with .copserc files, pass cwd parameter (already supported). Clean up in teardown. No mocking needed — loadConfig already accepts a cwd argument.

File changes: New file tests/config.test.ts.

4. tests/create-prs-helpers.test.ts — Helper functions from commands/create-prs.ts

What to test:

Function	Test Cases
parseCommitMessage	Subject only, subject + body, empty message, multi-line body, leading/trailing whitespace
buildPRBody	Template + commit body (joined with ---), template only, commit body only, both empty returns undefined

Approach: These functions are currently not exported. They need to be extracted or exported for testing.

Trade-off: Either (a) export them from commands/create-prs.ts, or (b) move them to a shared lib/ module. Option (a) is simpler and more pragmatic — just add export to the function declarations.

File changes:

• Modify commands/create-prs.ts — add export to parseCommitMessage and buildPRBody
• New file tests/create-prs-helpers.test.ts

5. tests/create-issue-helpers.test.ts — Helper functions from commands/create-issue.ts

What to test:

Function	Test Cases
stripFrontmatter	Content with YAML frontmatter, no frontmatter (passthrough), --- appearing in body content, Windows line endings (\r\n), empty content
buildIssueBody	Template + user body, template only, user body only, both null returns undefined
isAgent	Recognizes "cursor", "claude", "copilot", case-insensitive, rejects unknown strings, rejects undefined/empty

Approach: Same trade-off as above — these are private functions. Need export added.

File changes:

• Modify commands/create-issue.ts — add export to stripFrontmatter, buildIssueBody, isAgent
• New file tests/create-issue-helpers.test.ts

CI Change

6. .github/workflows/ci.yml — Run tests in CI

Current gap: Unit tests are never run in CI. This is the single most impactful change.

Change: Add a Run tests step after the Build step:

- name: Run tests
  run: npm test

This ensures all existing and new tests gate PRs going forward.

Summary of Files Changed

File	Action	Purpose
tests/gh-validation.test.ts	New	Test validateRepo, validateAgent, matchesAgent, getAgentForPR, isBotPR, formatGhError
tests/args.test.ts	New	Test all arg parsing functions
tests/config.test.ts	New	Test config loading with temp .copserc files
tests/create-prs-helpers.test.ts	New	Test parseCommitMessage, buildPRBody
tests/create-issue-helpers.test.ts	New	Test stripFrontmatter, buildIssueBody, isAgent
commands/create-prs.ts	Edit	Export parseCommitMessage, buildPRBody
commands/create-issue.ts	Edit	Export stripFrontmatter, buildIssueBody, isAgent
.github/workflows/ci.yml	Edit	Add npm test step

Trade-offs

1. Exporting private helpers — Adding export to parseCommitMessage, buildPRBody, stripFrontmatter, buildIssueBody, and isAgent slightly expands the public surface of command modules. The alternative (moving to lib/) is cleaner architecturally but a bigger refactor. I'd recommend starting with export and refactoring later if the helpers are reused.

2. Config tests use the filesystem — loadConfig reads real files and walks directories. Tests will create temporary directories, which adds minor I/O but avoids mocking the fs module (no test doubles library is in use).

3. No mocking framework — The project has zero test dependencies. Functions that call gh (like checkPRsForAgentCoAuthors, listOpenPRs, getCurrentUser) cannot be unit tested without a mocking library or dependency injection. This plan focuses on pure functions that can be tested without mocking, which covers the most regression-prone logic. Adding a mock library (e.g., the built-in node:test mock API available in Node 20+) could be a follow-up for testing gh-dependent code paths.

4. Scope boundary — The status.ts TUI (~1000 lines) has testable helpers (getUrgency, matchesSearch, truncatePlain, visibleLength) but they're deeply embedded in the module. Testing those would require either exporting them or extracting to lib/. I'd recommend deferring that to a separate PR to keep this one focused.

5. Estimated test count — ~35-40 individual test cases across the 5 new files, covering the highest-risk pure logic paths.