From ba7fa316a8e06be7e8849f900b1430019553ad9f Mon Sep 17 00:00:00 2001 From: Rob Donigian Date: Fri, 9 May 2025 11:28:59 -0400 Subject: [PATCH 1/2] copiot instructions --- .github/copilot-instructions.md | 125 ++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..b36987a59 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,125 @@ +# Copilot Instructions + +This project is a web application built with React 18, Material-UI (MUI), and GraphQL, using Yarn as the package manager and Razzle for the custom build process. Follow these guidelines to ensure consistent, high-quality code aligned with our coding standards. + +## Coding Standards + +- Use camelCase for variables, functions, and methods. +- Use PascalCase for React components, classes, and enums. +- Use kebab-case for new folders and files. +- Use single quotes for strings. +- Use 2 spaces for indentation. +- Prefer arrow functions for callbacks. +- Use async/await for GraphQL queries and mutations. +- Use const for constants, let for reassignable variables. +- Use destructuring for objects and arrays. +- Use template literals for dynamic strings. +- Follow SOLID principles for modular, reusable, and maintainable code. +- Avoid code duplication, deeply nested statements, and hard-coded values (e.g., file paths, usernames). +- Use constants or enums instead of magic numbers/strings for readability and memory efficiency. + +## Project Preferences + +- Use React with functional components and hooks. +- Use Material-UI (MUI) v5 for UI components and styling: + - Use the `sx` prop as the primary styling method. + - Avoid `useStyles` or `makeStyles` (MUI v4 patterns). + - Reference `src/theme` for custom MUI theme configurations in `sx` (e.g., `sx={{ color: theme.palette.primary.main }}`). +- Use Apollo Client for GraphQL: + - Write type-safe queries and mutations with generated TypeScript types. + - Store queries, mutations, and fragments in `src/api`. +- Use Yarn for package management: + - Run `yarn add` for dependencies, checking for vulnerabilities with Snyk. + - Use `yarn start`, `yarn build`, and `yarn test` for Razzle scripts. +- Custom build process with Razzle: + - Configure Razzle in `razzle.config.js` for build settings. + - Optimize for production with code splitting and server-side rendering (SSR). + - Use `src/server` for Razzle server configurations. +- Use TypeScript for all code: + - Enforce strict mode. + - Define interfaces and types in `src/common`. +- Follow folder structure: + - `src/api`: GraphQL queries, mutations, Apollo Client setup, and API-related files. + - `src/common`: Utility TypeScript files (types, interfaces, general-use TS). + - `src/components`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders. + - `src/hooks`: Custom React hooks (TypeScript). + - `src/scenes`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders. + - `src/server`: Razzle server configuration files. + - `src/theme`: MUI theme configuration files. + +## Version Control + +- Create branches with format: `type/MondayTicketID-description` (e.g., `enhancement/1234-new-profile-page`). +- Write commit messages: + - First line: `[TicketID] - [Short Title] - Imperative verb` (e.g., `0654 - IRP - Remove/move Impact Report Date`). + - Optional body: Briefly explain why the change is needed or the problem addressed. +- Create PRs for single, specific changes (one user story per PR unless deployable in isolation): + - Link the Monday ticket in the PR description. + - Break changes into bite-sized, logical commits for easier review and potential reversion. + - Demo functionality to reviewers when needed. + +## Security Practices + +- Sanitize all user inputs to prevent XSS. +- Use Apollo Client’s error handling for GraphQL responses in `src/api`. +- Implement role-based access control (RBAC) via GraphQL context. +- Configure secure cookies (`HttpOnly`, `Secure`, `SameSite=Strict`) in `src/server`. +- Enforce Content Security Policy (CSP) in Razzle’s server configuration in `src/server`. +- Validate data from external sources (APIs, databases) for expected formats. +- Check new dependencies with Snyk for vulnerabilities before adding via Yarn. + +## Form Development + +- Use custom form components built with Final Form and react-final-form in `src/components/form`: + - Use components like `Form`, `Field`, and custom inputs for consistent behavior. + - Define TypeScript interfaces in `src/common` for form data and props. + - Use `react-final-form` hooks (e.g., `useForm`, `useField`) for form state management. +- Integrate MUI v5 components (`TextField`, `Select`, etc.) within form components: + - Apply `sx` prop, referencing `src/theme` for consistency. +- Use `yup` for validation: + - Store schemas in `src/common/validation`. + - Ensure TypeScript compatibility. + - Integrate with react-final-form for user-friendly error messages. + +## General Guidelines + +- Write clear, concise code with single-responsibility modules. +- Add JSDoc comments for public functions and components (optional: include purpose and description). +- Optimize performance: + - Use `React.memo`, `useCallback`, `useMemo` for React components. + - Minimize loop iterations, redundant operations, and memory allocations. + - Process data in chunks for large datasets. + - Optimize GraphQL queries in `src/api` for efficient data retrieval. +- Avoid changing code outside the task scope; create separate PRs for refactors. +- Keep responses friendly, informal, and under 1000 characters. +- Reference `styleguide.md` in `docs/` for additional styling rules. + +## Testing + +- Use Jest and React Testing Library for unit tests: + - Place tests in `__tests__` folders in `src/components` and `src/scenes`. + - Mock GraphQL queries with `@apollo/client/testing` for `src/api` files. + - Mock react-final-form for form tests using `react-final-form` testing utilities. +- Write descriptive tests focusing on user interactions. +- Ensure functional quality: + - Unit testing in development. + - Regression and smoke testing in production or development as needed. +- Validate all acceptance criteria in PR reviews. + +## Additional Notes + +- Reference GraphQL schemas in `src/api/schema.graphql`. +- Avoid external resource references unless specified. +- If instructions seem ignored, remind Copilot to check this file.- Use tagged comments (`// cp tag`) to mark code for reference: + - `example`: Best practice or model code. + - `edge-case`: Necessary deviation from standards. + - `best-practice`: Adherence to coding standards. + - `anti-pattern`: Code to avoid (pending refactor). + - `todo`: Needs improvement or refactoring. + - `workaround`: Temporary fix for a limitation. + - `performance`: Optimized code. + - `security`: Security-critical code. + - `test`: Exemplary test case. + - `design-alignment`: Matches or deviates from design specs. +- After the tag, optionally add notes to explain the context (e.g., `// cp example Reusable form with theme-based styling`). +- Search for tags with `git grep "cp "` to collect examples for this document. From 0df8aab4fe5b2bb0ff339a00e4d0c12e1eff9887 Mon Sep 17 00:00:00 2001 From: Rob Donigian Date: Thu, 15 May 2025 08:35:40 -0400 Subject: [PATCH 2/2] create ai guidelines --- .github/copilot-instructions.md | 268 ++++++++++++++++++-------------- .junie/guidelines.md | 163 +++++++++++++++++++ 2 files changed, 316 insertions(+), 115 deletions(-) create mode 100644 .junie/guidelines.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b36987a59..d18f27564 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,116 +1,153 @@ -# Copilot Instructions - -This project is a web application built with React 18, Material-UI (MUI), and GraphQL, using Yarn as the package manager and Razzle for the custom build process. Follow these guidelines to ensure consistent, high-quality code aligned with our coding standards. - -## Coding Standards - -- Use camelCase for variables, functions, and methods. -- Use PascalCase for React components, classes, and enums. -- Use kebab-case for new folders and files. -- Use single quotes for strings. -- Use 2 spaces for indentation. -- Prefer arrow functions for callbacks. -- Use async/await for GraphQL queries and mutations. -- Use const for constants, let for reassignable variables. -- Use destructuring for objects and arrays. -- Use template literals for dynamic strings. -- Follow SOLID principles for modular, reusable, and maintainable code. -- Avoid code duplication, deeply nested statements, and hard-coded values (e.g., file paths, usernames). -- Use constants or enums instead of magic numbers/strings for readability and memory efficiency. - -## Project Preferences - -- Use React with functional components and hooks. -- Use Material-UI (MUI) v5 for UI components and styling: - - Use the `sx` prop as the primary styling method. - - Avoid `useStyles` or `makeStyles` (MUI v4 patterns). - - Reference `src/theme` for custom MUI theme configurations in `sx` (e.g., `sx={{ color: theme.palette.primary.main }}`). -- Use Apollo Client for GraphQL: - - Write type-safe queries and mutations with generated TypeScript types. - - Store queries, mutations, and fragments in `src/api`. -- Use Yarn for package management: - - Run `yarn add` for dependencies, checking for vulnerabilities with Snyk. - - Use `yarn start`, `yarn build`, and `yarn test` for Razzle scripts. -- Custom build process with Razzle: - - Configure Razzle in `razzle.config.js` for build settings. - - Optimize for production with code splitting and server-side rendering (SSR). - - Use `src/server` for Razzle server configurations. -- Use TypeScript for all code: - - Enforce strict mode. - - Define interfaces and types in `src/common`. -- Follow folder structure: - - `src/api`: GraphQL queries, mutations, Apollo Client setup, and API-related files. - - `src/common`: Utility TypeScript files (types, interfaces, general-use TS). - - `src/components`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders. - - `src/hooks`: Custom React hooks (TypeScript). - - `src/scenes`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders. - - `src/server`: Razzle server configuration files. - - `src/theme`: MUI theme configuration files. - -## Version Control - -- Create branches with format: `type/MondayTicketID-description` (e.g., `enhancement/1234-new-profile-page`). -- Write commit messages: - - First line: `[TicketID] - [Short Title] - Imperative verb` (e.g., `0654 - IRP - Remove/move Impact Report Date`). - - Optional body: Briefly explain why the change is needed or the problem addressed. -- Create PRs for single, specific changes (one user story per PR unless deployable in isolation): - - Link the Monday ticket in the PR description. - - Break changes into bite-sized, logical commits for easier review and potential reversion. - - Demo functionality to reviewers when needed. - -## Security Practices - -- Sanitize all user inputs to prevent XSS. -- Use Apollo Client’s error handling for GraphQL responses in `src/api`. -- Implement role-based access control (RBAC) via GraphQL context. -- Configure secure cookies (`HttpOnly`, `Secure`, `SameSite=Strict`) in `src/server`. -- Enforce Content Security Policy (CSP) in Razzle’s server configuration in `src/server`. -- Validate data from external sources (APIs, databases) for expected formats. -- Check new dependencies with Snyk for vulnerabilities before adding via Yarn. - -## Form Development - -- Use custom form components built with Final Form and react-final-form in `src/components/form`: - - Use components like `Form`, `Field`, and custom inputs for consistent behavior. - - Define TypeScript interfaces in `src/common` for form data and props. - - Use `react-final-form` hooks (e.g., `useForm`, `useField`) for form state management. -- Integrate MUI v5 components (`TextField`, `Select`, etc.) within form components: - - Apply `sx` prop, referencing `src/theme` for consistency. -- Use `yup` for validation: - - Store schemas in `src/common/validation`. - - Ensure TypeScript compatibility. - - Integrate with react-final-form for user-friendly error messages. - -## General Guidelines - -- Write clear, concise code with single-responsibility modules. -- Add JSDoc comments for public functions and components (optional: include purpose and description). -- Optimize performance: - - Use `React.memo`, `useCallback`, `useMemo` for React components. - - Minimize loop iterations, redundant operations, and memory allocations. - - Process data in chunks for large datasets. - - Optimize GraphQL queries in `src/api` for efficient data retrieval. -- Avoid changing code outside the task scope; create separate PRs for refactors. -- Keep responses friendly, informal, and under 1000 characters. -- Reference `styleguide.md` in `docs/` for additional styling rules. - -## Testing - -- Use Jest and React Testing Library for unit tests: - - Place tests in `__tests__` folders in `src/components` and `src/scenes`. - - Mock GraphQL queries with `@apollo/client/testing` for `src/api` files. - - Mock react-final-form for form tests using `react-final-form` testing utilities. -- Write descriptive tests focusing on user interactions. -- Ensure functional quality: - - Unit testing in development. - - Regression and smoke testing in production or development as needed. -- Validate all acceptance criteria in PR reviews. - -## Additional Notes - -- Reference GraphQL schemas in `src/api/schema.graphql`. -- Avoid external resource references unless specified. -- If instructions seem ignored, remind Copilot to check this file.- Use tagged comments (`// cp tag`) to mark code for reference: +# CORD Front-End Development Guidelines + +This document provides guidelines for developers working on the CORD Field front-end project, a UI built with React, Material-UI (MUI) v5, and GraphQL, using Yarn and Razzle. The front-end connects to the CORD API v3. + +### Project Structure + +- `src/`: Source code + - `src/api/`: client setup, caching strategies, schema definitions, and operation management. + - `src/common/`: Utility TypeScript files (types, interfaces). + - `src/components/`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders (e.g., `form/` for Final Form components). + - `src/hooks/`: Custom React hooks (TypeScript). + - `src/scenes/`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders. + - `src/server/`: server-side code and configuration files. + - `src/theme/`: MUI theme configuration files. + +### Coding Standards + +- Use single quotes for strings, 2 spaces for indentation. +- Prefer arrow functions for callbacks, async/await for GraphQL queries/mutations. +- Use `const` for constants, minimize `let` usage (e.g., except in try/catch). +- Use destructuring for objects/arrays, template literals for strings. +- Follow SOLID principles for modular, reusable, maintainable code. +- Avoid code duplication, deeply nested statements, hard-coded values. +- Use constants/enums instead of magic numbers/strings. +- Avoid mutations (non-GraphQL): + - Prefer `const` over `let`. + - Use spread syntax (e.g., `{ ...object, foo: 'bar' }`) instead of modifying objects. +- Use strict TypeScript: + - Define all object shapes in `src/common` or generated GraphQL types in `src/api`. + - Use optional chaining (`?.`) or type guards for safe property access. + +### React Guidelines + +- For new small components: + - Pass most props to wrapping components for reusability. + - Match designs or comment stop-gap versions. +- Avoid unnecessary HTML elements for styling (e.g., `` instead of ``). +- Use optional chaining (`?.`) or type guards for object properties. + +### Form Development + +- Use custom form components with Final Form and react-final-form in `src/components/form`. + +### CSS Guidelines + +- Use `sx` prop for styling; avoid StyledComponents or `makeStyles`. +- Reference `src/theme` for spacing (1-8), palette colors, typography variants. +- Comment if using magic numbers/colors/fonts. +- Ensure styles are minimal, necessary, and responsive across screen sizes. +- Use `// ai edge-case` for justified deviations (e.g., non-theme colors). +- **Parent components own layout styles**: Apply layout-related styles (e.g., centering, alignment, spacing) to parent components, not children, to ensure encapsulation and reusability. + - Example (Correct): + ```tsx + // ai example Parent-owned centering + // src/components/CenteredCard.tsx + import { Box, Card } from '@mui/material'; + export const CenteredCard = () => ( + + Content + + ); + ``` + _Why_: Parent `` controls centering, keeping `` reusable. + - Example (Incorrect): + ```tsx + // ai anti-pattern Child-owned centering + // src/components/CenteredCard.tsx + import { Box, Card } from '@mui/material'; + export const CenteredCard = () => ( + + Content + + ); + ``` + _Why_: `` assumes parent’s layout, reducing reusability. +- **Order control styles before appearance styles**: In `sx` prop declarations, list control styles (e.g., `display`, `padding`, `width`) before appearance styles (e.g., `color`, `background`, `fontSize`) for readability. + - Example (Correct): + ```tsx + // ai example Ordered sx styles + // src/components/StyledBox.tsx + import { Box } from '@mui/material'; + export const StyledBox = () => ( + + Content + + ); + ``` + _Why_: Control styles (`display`, `justifyContent`, `padding`, `width`) precede appearance styles (`backgroundColor`, `color`, `borderRadius`, `fontSize`), enhancing readability. + - Example (Incorrect): + ```tsx + // ai anti-pattern Disordered sx styles + // src/components/StyledBox.tsx + import { Box } from '@mui/material'; + export const StyledBox = () => ( + + Content + + ); + ``` + _Why_: Mixed style order reduces readability and maintainability. + +### Common Errors to Avoid + +- **Accessing Non-Existent Properties**: + - Never assume properties exist without type verification. + - Reference TypeScript interfaces in `src/common` or generated GraphQL types in `src/api`. + - Use optional chaining (`?.`) or type guards (e.g., `if ('foo' in obj)`). + - Example (Correct): + ```tsx + // ai type-safety Safe property access with optional chaining + interface User { + name?: string; + } + const user: User = {}; + const name = user?.name ?? 'Unknown'; + ``` + _Why_: Prevents runtime errors by checking property existence. + - Example (Incorrect): + ```tsx + // ai anti-pattern Assumes non-existent property + const user = {}; + const name = user.name; // Error: Property 'name' does not exist + ``` + _Why_: Causes runtime errors due to unverified property access. + +### Tagged Comments + +- Use `// ai tag` to mark code for reference: - `example`: Best practice or model code. - `edge-case`: Necessary deviation from standards. - `best-practice`: Adherence to coding standards. @@ -121,5 +158,6 @@ This project is a web application built with React 18, Material-UI (MUI), and Gr - `security`: Security-critical code. - `test`: Exemplary test case. - `design-alignment`: Matches or deviates from design specs. -- After the tag, optionally add notes to explain the context (e.g., `// cp example Reusable form with theme-based styling`). -- Search for tags with `git grep "cp "` to collect examples for this document. + - `type-safety`: Safe property access. +- Optionally add notes after the tag (e.g., `// ai example Reusable form with theme-based styling`). +- Search tags with `git grep "ai "` to collect examples. diff --git a/.junie/guidelines.md b/.junie/guidelines.md new file mode 100644 index 000000000..d18f27564 --- /dev/null +++ b/.junie/guidelines.md @@ -0,0 +1,163 @@ +# CORD Front-End Development Guidelines + +This document provides guidelines for developers working on the CORD Field front-end project, a UI built with React, Material-UI (MUI) v5, and GraphQL, using Yarn and Razzle. The front-end connects to the CORD API v3. + +### Project Structure + +- `src/`: Source code + - `src/api/`: client setup, caching strategies, schema definitions, and operation management. + - `src/common/`: Utility TypeScript files (types, interfaces). + - `src/components/`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders (e.g., `form/` for Final Form components). + - `src/hooks/`: Custom React hooks (TypeScript). + - `src/scenes/`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders. + - `src/server/`: server-side code and configuration files. + - `src/theme/`: MUI theme configuration files. + +### Coding Standards + +- Use single quotes for strings, 2 spaces for indentation. +- Prefer arrow functions for callbacks, async/await for GraphQL queries/mutations. +- Use `const` for constants, minimize `let` usage (e.g., except in try/catch). +- Use destructuring for objects/arrays, template literals for strings. +- Follow SOLID principles for modular, reusable, maintainable code. +- Avoid code duplication, deeply nested statements, hard-coded values. +- Use constants/enums instead of magic numbers/strings. +- Avoid mutations (non-GraphQL): + - Prefer `const` over `let`. + - Use spread syntax (e.g., `{ ...object, foo: 'bar' }`) instead of modifying objects. +- Use strict TypeScript: + - Define all object shapes in `src/common` or generated GraphQL types in `src/api`. + - Use optional chaining (`?.`) or type guards for safe property access. + +### React Guidelines + +- For new small components: + - Pass most props to wrapping components for reusability. + - Match designs or comment stop-gap versions. +- Avoid unnecessary HTML elements for styling (e.g., `` instead of ``). +- Use optional chaining (`?.`) or type guards for object properties. + +### Form Development + +- Use custom form components with Final Form and react-final-form in `src/components/form`. + +### CSS Guidelines + +- Use `sx` prop for styling; avoid StyledComponents or `makeStyles`. +- Reference `src/theme` for spacing (1-8), palette colors, typography variants. +- Comment if using magic numbers/colors/fonts. +- Ensure styles are minimal, necessary, and responsive across screen sizes. +- Use `// ai edge-case` for justified deviations (e.g., non-theme colors). +- **Parent components own layout styles**: Apply layout-related styles (e.g., centering, alignment, spacing) to parent components, not children, to ensure encapsulation and reusability. + - Example (Correct): + ```tsx + // ai example Parent-owned centering + // src/components/CenteredCard.tsx + import { Box, Card } from '@mui/material'; + export const CenteredCard = () => ( + + Content + + ); + ``` + _Why_: Parent `` controls centering, keeping `` reusable. + - Example (Incorrect): + ```tsx + // ai anti-pattern Child-owned centering + // src/components/CenteredCard.tsx + import { Box, Card } from '@mui/material'; + export const CenteredCard = () => ( + + Content + + ); + ``` + _Why_: `` assumes parent’s layout, reducing reusability. +- **Order control styles before appearance styles**: In `sx` prop declarations, list control styles (e.g., `display`, `padding`, `width`) before appearance styles (e.g., `color`, `background`, `fontSize`) for readability. + - Example (Correct): + ```tsx + // ai example Ordered sx styles + // src/components/StyledBox.tsx + import { Box } from '@mui/material'; + export const StyledBox = () => ( + + Content + + ); + ``` + _Why_: Control styles (`display`, `justifyContent`, `padding`, `width`) precede appearance styles (`backgroundColor`, `color`, `borderRadius`, `fontSize`), enhancing readability. + - Example (Incorrect): + ```tsx + // ai anti-pattern Disordered sx styles + // src/components/StyledBox.tsx + import { Box } from '@mui/material'; + export const StyledBox = () => ( + + Content + + ); + ``` + _Why_: Mixed style order reduces readability and maintainability. + +### Common Errors to Avoid + +- **Accessing Non-Existent Properties**: + - Never assume properties exist without type verification. + - Reference TypeScript interfaces in `src/common` or generated GraphQL types in `src/api`. + - Use optional chaining (`?.`) or type guards (e.g., `if ('foo' in obj)`). + - Example (Correct): + ```tsx + // ai type-safety Safe property access with optional chaining + interface User { + name?: string; + } + const user: User = {}; + const name = user?.name ?? 'Unknown'; + ``` + _Why_: Prevents runtime errors by checking property existence. + - Example (Incorrect): + ```tsx + // ai anti-pattern Assumes non-existent property + const user = {}; + const name = user.name; // Error: Property 'name' does not exist + ``` + _Why_: Causes runtime errors due to unverified property access. + +### Tagged Comments + +- Use `// ai tag` to mark code for reference: + - `example`: Best practice or model code. + - `edge-case`: Necessary deviation from standards. + - `best-practice`: Adherence to coding standards. + - `anti-pattern`: Code to avoid (pending refactor). + - `todo`: Needs improvement or refactoring. + - `workaround`: Temporary fix for a limitation. + - `performance`: Optimized code. + - `security`: Security-critical code. + - `test`: Exemplary test case. + - `design-alignment`: Matches or deviates from design specs. + - `type-safety`: Safe property access. +- Optionally add notes after the tag (e.g., `// ai example Reusable form with theme-based styling`). +- Search tags with `git grep "ai "` to collect examples.