From 12c059d45e278c85c68eb4132865adc22c6fe119 Mon Sep 17 00:00:00 2001 From: Tim Hostetler <6970899+thostetler@users.noreply.github.com> Date: Mon, 2 Mar 2026 09:26:14 -0500 Subject: [PATCH] add sectional instruction files for code review --- .github/copilot-instructions.md | 38 +++++++++++++++++++ .../instructions/api-and-data.instructions.md | 24 ++++++++++++ .../frontend-review.instructions.md | 21 ++++++++++ .../testing-and-mocks.instructions.md | 20 ++++++++++ 4 files changed, 103 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/instructions/api-and-data.instructions.md create mode 100644 .github/instructions/frontend-review.instructions.md create mode 100644 .github/instructions/testing-and-mocks.instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..2f0b67c75 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,38 @@ +# Nectar repository-wide Copilot instructions + +## Primary objective +Act as a senior reviewer for a Next.js + TypeScript application. Prioritize **correctness, security, regression risk, and operability** over stylistic suggestions. + +## Review output style +- Start with a short risk summary. +- Report findings in priority order: `blocker`, `high`, `medium`, `low`. +- For each finding include: + - impact (what can break and for whom), + - precise location(s), + - minimal fix recommendation, + - confidence level (`high`/`medium`/`low`). +- If no issues are found, state what was reviewed and what remains unverified. + +## Project-specific baselines +- Stack: Next.js, React, TypeScript, Chakra UI, Vitest, MSW. +- Package manager: **pnpm only**. +- Typical local checks: + 1. `pnpm lint` + 2. `pnpm test:ci` + 3. `pnpm build` (or `pnpm build:local` when requested) +- Dev server defaults to port `8000`. + +## What to scrutinize first +1. API contract changes across `src/api`, `src/pages/api`, and consumers. +2. Rendering/data-fetching behavior in `src/pages` and shared components. +3. State/query/cache correctness in `src/lib`, `src/store`, and hooks. +4. Test coverage for behavioral changes (`*.test.ts(x)`, `src/mocks`). + +## Security and reliability guardrails +- Flag potential secrets exposure, unsafe env handling, or permissive logging. +- Validate sanitization/escaping for user-controlled content. +- Check error paths and loading/empty states, not only happy paths. +- Highlight breaking API shape changes and migration needs. + +## Non-goals +- Avoid nitpicks already enforced by formatter/linter unless they hide real defects. diff --git a/.github/instructions/api-and-data.instructions.md b/.github/instructions/api-and-data.instructions.md new file mode 100644 index 000000000..534c32110 --- /dev/null +++ b/.github/instructions/api-and-data.instructions.md @@ -0,0 +1,24 @@ +--- +applyTo: "src/api/**/*.ts,src/pages/api/**/*.ts,src/lib/**/*.ts,src/store/**/*.ts,src/middleware/**/*.ts,src/middlewares/**/*.ts" +--- + +# API, data, and server-side review instructions + +## Contract and schema integrity +- Detect response/request shape changes and verify all callers are updated. +- Prefer explicit typing for external data boundaries; flag `any` at API edges. +- Ensure query parameter parsing and defaults are deterministic. + +## Error handling and observability +- Ensure failures return actionable status codes/messages without leaking internals. +- Verify retries/timeouts/caching behavior do not cause stale or duplicated data. +- Confirm logging captures useful diagnostics while avoiding sensitive payloads. + +## State and cache correctness +- Check for race conditions in async flows and stale closure issues. +- Validate cache invalidation and key stability for React Query/store selectors. +- Flag mutation flows that do not reconcile local state with server truth. + +## Security checks +- Validate auth/authorization assumptions on route handlers and middleware. +- Flag open redirect, injection, and unsafe header/cookie usage patterns. diff --git a/.github/instructions/frontend-review.instructions.md b/.github/instructions/frontend-review.instructions.md new file mode 100644 index 000000000..3ed6140c0 --- /dev/null +++ b/.github/instructions/frontend-review.instructions.md @@ -0,0 +1,21 @@ +--- +applyTo: "src/components/**/*.ts,src/components/**/*.tsx,src/pages/**/*.ts,src/pages/**/*.tsx,src/styles/**/*.css" +--- + +# Frontend review instructions (React/Next.js) + +## Focus areas +- Verify SSR/CSR behavior is intentional (no browser-only APIs during SSR without guards). +- Confirm route-level pages maintain expected metadata, loading, and error behavior. +- Check Chakra UI usage for accessibility regressions: semantic controls, labels, keyboard navigation, focus visibility. +- Validate conditional rendering to avoid layout flicker and hydration mismatches. + +## Performance checks +- Flag unnecessary rerenders from unstable props/callbacks in hot paths. +- Watch for expensive client-side transforms that should be memoized or moved server-side. +- Ensure large dependencies are not added to shared/page-critical bundles without justification. + +## UX regression checklist +- Empty, loading, and error states are explicit and user-friendly. +- Interactive controls have disabled and busy states when async operations run. +- New text is concise and consistent with existing naming/terminology. diff --git a/.github/instructions/testing-and-mocks.instructions.md b/.github/instructions/testing-and-mocks.instructions.md new file mode 100644 index 000000000..543d9221e --- /dev/null +++ b/.github/instructions/testing-and-mocks.instructions.md @@ -0,0 +1,20 @@ +--- +applyTo: "**/*.test.ts,**/*.test.tsx,src/mocks/**/*.ts" +--- + +# Testing and mocking review instructions + +## Test quality expectations +- Tests should assert behavior, not implementation details. +- New logic paths should include at least one success path and one failure/edge path. +- Prefer deterministic tests (no real network/time randomness unless controlled). + +## Vitest and Testing Library guidance +- Verify async UI tests wait for user-visible outcomes. +- Ensure queries prefer accessible roles/labels over brittle selectors. +- Flag snapshots that replace meaningful assertions. + +## MSW/mocks guidance +- Mocks should reflect realistic API contracts and error payloads. +- When changing endpoint behavior, update handlers and impacted tests together. +- Avoid over-mocking internal modules when an integration-style test is feasible.