clean-code

name	clean-code
description	Clean code and structure standards for this repo. Use when writing or refactoring any TypeScript/React code — covers naming, file layout, typing, and testing discipline.

Clean Code

Optimize for the next reader. This repo is a template people clone repeatedly — every pattern in it gets copied, so every pattern must be worth copying.

TypeScript discipline

• Strict mode is on; keep it meaningful: no any, no as unknown as, no ! non-null assertions to silence errors you should fix.
• Derive types instead of duplicating them: z.infer<typeof Schema>, ComponentProps<typeof Button>, ReturnType<...>.
• Type function boundaries (params, return values); let inference handle locals.
• Model states that can't coexist as discriminated unions, not boolean soup (status: "idle" | "loading" | "error" beats isLoading + isError).

Naming

• Components: PascalCase. Hooks: useCamelCase. Everything else: camelCase. Files: match the main export (user-card.tsx exporting UserCard — kebab-case files, per shadcn convention).
• Names say what, not how: activeUsers, not filteredArr.
• Booleans read as predicates: isOpen, hasAccess, canEdit.
• No abbreviations that save three characters at the cost of a mental lookup.

Structure

• src/app/ — routes only (pages, layouts, route handlers).
• src/components/ui/ — shadcn primitives (managed by the CLI, don't hand-edit).
• src/components/ — shared feature components composed from primitives.
• src/lib/ — pure utilities, schemas, clients. No React in lib/.
• Small components: when a component needs a scroll to read, extract pieces.
• Co-locate what changes together; extract only on the second use, not speculatively.

Functions & flow

• Early returns over nested if/else pyramids.
• No dead code, no commented-out code, no console.log left behind — git remembers.
• Comments explain why (constraints, gotchas), never what the next line does.
• Don't catch errors you can't handle; let them reach the error boundary with context.

Testing discipline

• Test behavior, not implementation: query by role/label (getByRole("button", { name: /save/i })), never by class names or test IDs when a semantic query exists.
• Every bug fix gets a test that fails without the fix.
• Tests live in src/__tests__/ or co-located as *.test.tsx.

Commits

• Conventional Commits, enforced by commitlint: feat:, fix:, docs:, refactor:...
• One logical change per commit; subject in imperative mood, ≤ 72 chars.