Reviewing Source Code Changes

Name: repo-source-code-review
Rating: 92
Author: open-circle

Guide for reviewing PRs and source code changes in /library/src/.

When to Use This Guide

•Reviewing pull requests modifying library source
•Validating implementation patterns before merging
•Checking code quality, types, documentation, and tests

Review Process

•Understand the change — Read PR description, identify affected files
•Check patterns — Verify code follows existing conventions
•Verify types — Ensure type safety and proper inference
•Review docs — Confirm JSDoc is complete and accurate
•Check tests — Validate runtime and type test coverage

What to Review

Code Quality

Check	Requirement
Naming	Matches existing patterns (`StringSchema`, `minLength`, `_parse`)
Purity annotation	`// @__NO_SIDE_EFFECTS__` before pure factory functions
Import extensions	All imports use `.ts` extension
Interface vs type	Use `interface` for object shapes, `type` for unions/aliases
Folder structure	Each API has: `name.ts`, `name.test.ts`, `name.test-d.ts`, `index.ts`

Good — purity annotation:

typescript

// @__NO_SIDE_EFFECTS__
export function string(message?: ErrorMessage<StringIssue>): StringSchema {
  return {
    /* ... */
  };
}

Bad — missing annotation:

typescript

export function string(message?: ErrorMessage<StringIssue>): StringSchema {
  return {
    /* ... */
  };
}

Type Safety

Check	Requirement
Generic inference	Types infer correctly without explicit annotations
Constraints	Generic parameters have appropriate `extends` clauses
Return types	Explicit return types on exported functions
Type tests	`.test-d.ts` file covers type inference scenarios

Good — constrained generic:

typescript

export function minLength<
  TInput extends LengthInput,
  TRequirement extends number,
>(
  requirement: TRequirement,
  message?: ErrorMessage<MinLengthIssue<TInput, TRequirement>>
): MinLengthAction<TInput, TRequirement>;

Documentation

Check	Requirement
JSDoc present	All exported functions have JSDoc
First line	Action verb matching function purpose (see below)
`@param` tags	Every parameter documented
`@returns` tag	Return value documented
Overloads	Every overload has its own complete JSDoc block

First line patterns by category:

Category	Pattern
Schemas	`Creates a ... schema.`
Actions	`Creates a ... action.`
Parse methods	`Parses ...`
Type guards	`Checks if ...`
Unwrap methods	`Unwraps ...`
Other methods	`Creates a ...`, `Returns ...`, `Forwards ...`

See repo-source-code-document skill for full documentation rules.

Tests

Check	Requirement
Runtime tests	`.test.ts` covers success cases, failure cases, edge cases
Type tests	`.test-d.ts` validates type inference with `expectTypeOf`
Issue messages	Tests verify correct error messages and issue structure

Common Issues

Issue	What to Look For
Missing purity annotation	Factory function without `// @__NO_SIDE_EFFECTS__`
Incomplete JSDoc	Missing `@param` or `@returns`, wrong description format
No type tests	New API without `.test-d.ts` file
Wrong import extension	Imports without `.ts` suffix
Inconsistent naming	Schema not ending in `Schema`, action not ending in `Action`
Side effects in pure code	Mutations, I/O, or global state in schema/action creation

Checklist

• Implementation follows existing patterns in similar files
• // @__NO_SIDE_EFFECTS__ on pure factory functions
• All imports use .ts extension
• interface used for object shapes
• JSDoc complete on all exports
• Runtime tests in .test.ts
• Type tests in .test-d.ts
• Naming conventions followed

Related Skills

•repo-structure-navigate — Navigate the codebase
•repo-source-code-document — JSDoc requirements