Coding standards

Standards and conventions for TypeScript CLI projects using Jules workflows. Follow these guidelines to keep code consistent, reviewable, and aligned with the repository's existing patterns.

Naming Conventions

Variables & Functions

1Use camelCase for local variables, function parameters, and function names.
2Use PascalCase for types, interfaces, enums, and classes.
3Use UPPER_SNAKE_CASE for constants and environment variable references.
4Boolean variables should use is, has, or should prefixes.

Files & Directories

Use kebab-case for file names: write-app-configuration.ts
Test files use .test.ts suffix, colocated with source
Index files should re-export, not contain implementation

TypeScript Guidelines

Prefer interface over type for object shapes
Avoid any — use unknown and narrow with type guards
Use readonly for properties that should not be mutated
Prefer const assertions for literal types
Use discriminated unions over optional fields for variant types

Documentation

1Public functions require JSDoc with @param and @returns.
2Internal helpers: JSDoc optional, but add a one-line comment if intent is non-obvious.
3Avoid documenting what the code already says — document why, not what.

Error Handling

Use typed error classes extending Error
Include context in error messages: what failed, why, and what to do
Never swallow errors silently — log or rethrow
Use Result<T, E> patterns for expected failure modes

Testing

Unit tests for pure logic; integration tests for IO and CLI commands
Test names should describe behavior: "returns merged object when arrays overlap"
Use describe blocks to group related tests
Prefer real objects over mocks where practical

PR Checklist

Variable and function names follow conventions above
No any types without explicit justification
Public API changes have updated JSDoc
Tests pass locally: pnpm test
Linter passes: pnpm lint
Type checker passes: pnpm type-check
No unrelated changes in the diff