create ai guidelines files

Author: rdonigian

.github/copilot-instructions.md

@@ -0,0 +1,387 @@
+# CORD API Development Guidelines
+
+This document provides guidelines for developers working on the CORD API v3 project, a backend built with NestJS, GraphQL, and Neo4j/Gel, using NodeJS and Docker. The API serves the CORD Field front-end.
+
+## Overview
+
+The CORD API v3 provides [describe functionality briefly, e.g., data management for field operations; replace with specific details if available]. It runs by default on `http://localhost:3000`. For a complete setup guide, see the [cord-docs wiki](https://github.com/SeedCompany/cord-docs/wiki#new-hire-on-boarding).
+
+## Build/Configuration Instructions
+
+### Prerequisites
+
+1. Docker (install from official website, not Homebrew).
+2. NodeJS (version as specified in `package.json`, currently >= 20.6).
+   - Check version with `node -v`. Upgrade if compatibility issues arise.
+3. Corepack enabled (`corepack enable`).
+4. Yarn (managed via Corepack).
+5. Gel CLI (`brew install geldata/tap/gel-cli`).
+
+### Setup
+
+1. Install dependencies:
+
+   ```bash
+   yarn
+   ```
+
+2. Start the Neo4j database using Docker:
+
+   ```bash
+   docker-compose up -d db
+   ```
+
+3. Set up Gel (next-gen database replacing Neo4j):
+   ```bash
+   gel project init
+   yarn gel:gen
+   ```
+
+### Development
+
+1. Start the development server:
+
+   ```bash
+   yarn start:dev
+   ```
+
+2. For debugging:
+
+   ```bash
+   yarn start:debug
+   ```
+
+3. For production:
+
+   ```bash
+   yarn start:prod
+   ```
+
+4. Generate GraphQL schema:
+
+   ```bash
+   yarn gel:gen
+   ```
+
+5. Clean build artifacts:
+
+   ```bash
+   yarn clean
+   ```
+
+6. Create database migrations:
+
+   ```bash
+   yarn gel:migration
+   ```
+
+7. Generate seed data:
+   ```bash
+   yarn gel:seed
+   ```
+
+## Testing Information
+
+### Testing Framework
+
+The project uses Jest for testing:
+
+- Unit tests: Located in `tests` folders alongside source code in `src/components`, with `.spec.ts` or `.test.ts` extensions.
+- End-to-end (E2E) tests: Located in `test` directory, with `.e2e-spec.ts` extension.
+
+### Running Tests
+
+1. Run unit tests:
+
+   ```bash
+   yarn test
+   ```
+
+2. Run E2E tests:
+
+   ```bash
+   yarn test:e2e
+   ```
+
+3. Run tests with coverage:
+   ```bash
+   yarn test:cov
+   ```
+
+### Writing Tests
+
+#### Unit Tests
+
+Unit tests should be placed in `tests` folders alongside the service or resolver, with a `.spec.ts` or `.test.ts` extension. For example:
+
+- `src/components/user/user.service.ts` → `src/components/user/tests/user.service.spec.ts`
+- `src/common/util.ts` → `src/common/tests/util.test.ts`
+
+Example unit test:
+
+```typescript
+// src/common/tests/util.test.ts
+import { firstOr } from '../util';
+
+describe('firstOr', () => {
+  it('should return the first item in the array', () => {
+    const items = [1, 2, 3];
+    const result = firstOr(items, () => new Error('Array is empty'));
+    expect(result).toBe(1);
+  });
+
+  it('should throw an error if the array is empty', () => {
+    const items: number[] = [];
+    expect(() => firstOr(items, () => new Error('Array is empty'))).toThrow(
+      'Array is empty',
+    );
+  });
+});
+```
+
+#### E2E Tests
+
+E2E tests should be placed in the `test` directory with an `.e2e-spec.ts` extension, testing GraphQL API endpoints.
+
+Example E2E test:
+
+```typescript
+// test/user.e2e-spec.ts
+import { createTestApp, gql, TestApp } from './utility';
+
+describe('User API', () => {
+  let app: TestApp;
+
+  beforeAll(async () => {
+    app = await createTestApp();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('should fetch a user by ID', async () => {
+    const result = await app.graphql.query({
+      query: gql`
+        query GetUser($id: ID!) {
+          user(id: $id) {
+            id
+            name
+          }
+        }
+      `,
+      variables: { id: '123' },
+    });
+    expect(result.user).toEqual({ id: '123', name: 'Alice' });
+  });
+});
+```
+
+## Additional Development Information
+
+### Code Style
+
+The project uses ESLint and Prettier for code formatting and linting:
+
+- Run `yarn lint` to check and fix linting issues.
+- Run `yarn format` to format code using Prettier.
+- Enforce TypeScript strict mode (`tsconfig.json` with `strict: true`).
+
+### GraphQL
+
+The project uses NestJS with GraphQL (graphql-yoga):
+
+- GraphQL schema is generated in `schema.graphql` via `yarn gel:gen`.
+- Resolvers are defined in `*.resolver.ts` files in `src/components`.
+- DTOs (Data Transfer Objects) are defined in `*.dto.ts` files.
+- Only access properties defined in DTOs or interfaces.
+
+### Database
+
+The API is transitioning from Neo4j to Gel:
+
+- Neo4j is used with the `cypher-query-builder` library for queries.
+- Gel is the next-gen database replacing Neo4j.
+- Create migrations with `yarn gel:migration` to update the database schema.
+- Generate seed data with `yarn gel:seed` for testing or development.
+
+### Project Structure
+
+- `src/`: Source code
+  - `src/common/`: Common utilities, decorators, and TypeScript interfaces.
+  - `src/components/`: Feature-specific modules (e.g., `user`, `order`), containing resolvers, services, DTOs, and tests subfolders.
+  - `src/core/`: Core functionality, such as database connections and GraphQL setup.
+- `test/`: E2E tests
+  - `test/utility/`: Test utilities (e.g., test app setup).
+- `dbschema/`: Database schema definitions and migrations.
+
+### Coding Standards
+
+- Use camelCase for variables, functions, and methods; ensure names are descriptive.
+- Use PascalCase for classes, interfaces, and enums.
+- Use kebab-case for new folders and files.
+- Use single quotes for strings, 2 spaces for indentation.
+- Prefer async/await for asynchronous operations.
+- 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:
+  - Prefer `const` over `let`.
+  - Use spread syntax (e.g., `{ ...object, foo: 'bar' }`) instead of modifying objects.
+- Use strict TypeScript:
+  - Define all object shapes in DTOs (`*.dto.ts`) or interfaces in `src/common`.
+  - Use type guards for safe property access (e.g., `if ('foo' in obj)`).
+
+### GraphQL Guidelines
+
+- Define resolvers in `*.resolver.ts` with clear input/output types.
+- Use DTOs for input validation and response shaping.
+- Avoid overfetching; include only necessary fields in queries.
+- Handle errors explicitly using NestJS’s error handling (e.g., `throw new BadRequestException()`).
+- Use `// ai example` to mark well-structured resolvers or DTOs.
+
+### Database Guidelines
+
+- Write Cypher queries for Neo4j using `cypher-query-builder` for type safety.
+- Create Gel migrations for schema changes (`yarn gel:migration`).
+- Validate query results against defined DTOs or interfaces.
+- Avoid direct database mutations outside services; encapsulate in `*.service.ts`.
+
+### Version Control
+
+- Create branches: `type/MondayTicketID-description` (e.g., `feature/1234-new-endpoint`).
+- Write commit messages:
+  - First line: `[TicketID] - [Short Title] - Imperative verb` (e.g., `0654 - Add user endpoint`).
+  - Optional body: Explain why the change is needed.
+- Create PRs for single changes:
+  - Link Monday ticket in description.
+  - Use bite-sized, logical commits.
+  - Demo functionality to reviewers.
+  - Check entire PR for applicability.
+  - Verify no incorrect property access; properties must match DTOs or interfaces.
+
+### Security Practices
+
+- Sanitize GraphQL inputs to prevent injection attacks.
+- Implement role-based access control (RBAC) in resolvers via GraphQL context.
+- Use environment variables for sensitive data (e.g., database credentials).
+- Configure secure CORS settings in `src/core`.
+- Validate all external data (e.g., API inputs, database results) against DTOs.
+- Check dependencies with Snyk before adding via Yarn.
+
+### Common Errors to Avoid
+
+- **Accessing Non-Existent Properties**:
+  - Never assume properties exist without type verification.
+  - Reference DTOs in `*.dto.ts` or interfaces in `src/common`.
+  - Use type guards (e.g., `if ('foo' in obj)`) or optional chaining (`?.`) for dynamic data.
+  - Example (Correct):
+    ```typescript
+    // ai type-safety Safe property access with type guard
+    interface User {
+      name?: string;
+    }
+    function getName(user: User): string {
+      return 'name' in user && user.name ? user.name : 'Unknown';
+    }
+    ```
+    _Why_: Prevents runtime errors by checking property existence.
+  - Example (Incorrect):
+    ```typescript
+    // ai anti-pattern Assumes non-existent property
+    interface User {
+      name?: string;
+    }
+    function getName(user: User): string {
+      return user.name; // Error: Property 'name' may be undefined
+    }
+    ```
+    _Why_: Causes runtime errors due to unverified property access.
+- **Unvalidated GraphQL Inputs**:
+  - Always validate inputs using DTOs or class-validator in resolvers.
+  - Use `// ai anti-pattern` to mark unvalidated inputs.
+
+### Type Checking
+
+Run `yarn type-check` to check for TypeScript errors without compiling the code.
+
+### Debugging
+
+- Use `yarn start:debug` to start the server in debug mode with breakpoints.
+- Use Jest debugger for tests: `yarn test --selectProjects Unit` with debugger attached.
+- Enable NestJS logging in `src/core` for request/response debugging.
+- Use Neo4j Desktop or Gel CLI (`gel query`) to inspect database state.
+
+### 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.
+  - `type-safety`: Safe property access.
+- Optionally add notes after the tag (e.g., `// ai example Type-safe resolver`).
+- Search tags with `git grep "ai "` to collect examples.
+
+## Project Structure
+
+- Place GraphQL resolvers in `src/components/*/resolver.ts`.
+- Place services in `src/components/*/service.ts`.
+- Place DTOs in `src/components/*/dto/*.dto.ts`.
+- Place interfaces in `src/common`.
+- Place unit tests in `src/components/*/tests/*.spec.ts`.
+- Place E2E tests in `test/*.e2e-spec.ts`.
+
+## Coding Standards
+
+- Use camelCase for variables/functions, PascalCase for classes/interfaces/DTOs, kebab-case for files/folders.
+- Use single quotes, 2-space indentation, async/await, and `const` over `let`.
+- Use strict TypeScript with DTOs (`*.dto.ts`) or interfaces (`src/common`).
+- Example:
+  ```typescript
+  // ai type-safety Safe property access
+  interface User {
+    name?: string;
+  }
+  function getName(user: User): string {
+    return 'name' in user && user.name ? user.name : 'Unknown';
+  }
+  ```
+
+## GraphQL and Database
+
+- Define resolvers in `*.resolver.ts` with DTOs and `class-validator`.
+- Use `cypher-query-builder` for Neo4j queries in `*.service.ts`.
+- Generate schema with `yarn gel:gen`.
+- Example:
+  ```typescript
+  // ai example Type-safe resolver
+  @Resolver(() => UserDto)
+  export class UserResolver {
+    @Query(() => UserDto)
+    async user(@Args('id') id: string): Promise<UserDto> {
+      return this.userService.findById(id);
+    }
+  }
+  ```
+
+## Testing
+
+- Use Jest for tests in `src/components/*/tests/*.spec.ts` (unit) and `test/*.e2e-spec.ts` (E2E).
+- Example:
+  ```typescript
+  // ai test Unit test
+  describe('UserService', () => {
+    it('should return user by ID', async () => {
+      const result = await userService.findById('123');
+      expect(result).toEqual({ id: '123', name: 'Alice' });
+    });
+  });
+  ```