Reviewing Source Code Changes

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

1. Understand the change — Read PR description, identify affected files
2. Check patterns — Verify code follows existing conventions
3. Verify types — Ensure type safety and proper inference
4. Review docs — Confirm JSDoc is complete and accurate
5. 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:

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

Bad — missing annotation:

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:

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