chore(test): container testing, bound jest workers, null test coverage (#1069)

Author: DerekRoberts

.github/copilot-instructions.md

@@ -0,0 +1,71 @@
+# GitHub Copilot & AI Coding Instructions for `nr-fom`
+
+## Project Architecture & Monorepo Overview
+`nr-fom` (Forest Operations Map) is an npm workspaces monorepo:
+* **`admin/`**: Angular 22 admin portal for Forest Clients and Ministry staff to create, edit, submit, and review FOMs.
+* **`public/`**: Angular 22 public-facing portal for citizens to discover FOMs and submit comments.
+* **`api/`**: NestJS 11 backend service utilizing TypeORM 1.0, PostgreSQL 18 with PostGIS spatial extensions, and Pino logging.
+* **`libs/client/typescript-ng/`**: Auto-generated Angular API client from OpenAPI (`@api-client`).
+* **`libs/utility/`**: Shared security, authentication, and common TypeScript helpers.
+
+---
+
+## 1. Containerized Execution Invariants (Podman / Docker)
+
+### Never Run Heavy Workloads on Bare Metal
+* **Rule**: Never run test runners (`jest`, `npm run test-unit`), compilations (`ng build`, `nest build`), or migrations directly on the host machine.
+* **Execution**: Always dispatch commands inside Podman containers:
+  ```bash
+  # Run unit tests inside containers
+  podman compose exec admin npm run test:admin
+  podman compose exec api npm run test:api
+  podman compose exec public npm run test:public
+
+  # Database migrations
+  podman compose exec api npm run db:migrate-main --workspace=api
+  ```
+* **Worker Concurrency**: Always bound test runner concurrency with `--maxWorkers=2` or `--runInBand` on all Jest scripts (`test-unit`, `test-unit-watch`, `test-e2e`, `test:cov`) to prevent host CPU and memory starvation.
+
+---
+
+## 2. Frontend Reactive & Null Safety Standards (Angular 22)
+
+### Reactive Resource & Signal Patterns
+* **`rxResource` Resolution**: When consuming an Angular `rxResource`, check `resource.hasValue()` rather than evaluating truthiness (`if (!resource.value())`). 
+  * A resolved `null` payload (e.g., when a forest client has no historical public notice) is a **resolved valid state**, not an uncompleted loading state.
+* **Signal Un-tracking**: Inside `effect()` blocks, wrap downstream initialization calls (such as `buildForm()`) in `untracked()` if only the primary resource signal should trigger re-computation.
+
+### Form Building & Null Safety
+* **Form Initialization**: Always guard against `null` responses when constructing `@rxweb/reactive-form-validators` models:
+  ```typescript
+  const formModel = new PublicNoticeForm(this.response ?? undefined);
+  this.formGroup = this.formBuilder.formGroup(formModel) as IFormGroup<PublicNoticeForm>;
+  ```
+* **Prohibit Unchecked Type Casting**: Avoid blindly casting to `as Partial<T>` or `as any` to silence TypeScript compiler diagnostics. Check and guard property existence explicitly.
+
+### Authorization & State Gating in UI
+* Always verify project workflow state (`project.workflowState.code === WorkflowStateEnum.INITIAL`) and client permissions (`user.isForestClient && user.isAuthorizedForClientId(...)`) before exposing destructive actions (delete, submit).
+* Distinguish between `isNewForm` (project has no associated record) and `editMode` (route state).
+
+---
+
+## 3. Backend API & TypeORM Standards (NestJS 11)
+
+### OpenAPI & DTO Contracts
+* Every nullable or optional field in a DTO must be explicitly annotated with `@ApiPropertyOptional()` so that auto-generated Angular clients accurately reflect the nullable contract.
+* Avoid returning untyped object literals; map entities directly to declared response DTOs.
+
+### Multi-Tenancy & Client Scoping
+* All mutating endpoints must validate the caller's JWT claims against the target entity's `forestClient.id` using `user.isAuthorizedForClientId(clientId)`.
+* Ministry users (`user.isMinistry`) have cross-client read and administrative review capabilities.
+
+---
+
+## 4. Test Suite Requirements
+
+* **Unit Tests**: Test suites must cover the full lifecycle matrix:
+  1. Unresolved / loading state.
+  2. Resolved `null` / empty state (zero-state scenarios).
+  3. Resolved valid entity state.
+  4. Error states (403, 404, 500).
+* **Mock Realism**: Do not mock services to return only happy-path truthy data. Write explicit regression tests for empty and boundary return values.

.gitignore

@@ -108,6 +108,7 @@ tmp*.sh
 .kilo/
 .tmp/
 .github/**-instructions.md
+!.github/copilot-instructions.md
 **.instructions.md
 .github/agents/**
 .github/skills/**

admin/package.json

@@ -5,8 +5,8 @@
   "scripts": {
     "start:admin": "ng serve --configuration development --host=0.0.0.0",
     "build:admin": "ng build --configuration production",
-    "test-unit": "jest --coverage",
-    "test-unit-watch": "jest --watch=true"
+    "test-unit": "jest --coverage --maxWorkers=2",
+    "test-unit-watch": "jest --watch=true --maxWorkers=2"
   },
   "private": true,
   "engines": {

admin/src/app/foms/fom-detail/fom-detail.component.spec.ts

@@ -266,5 +266,37 @@ describe('FomDetailComponent', () => {
       await createComponent(project({ workflowState: { code: 'INITIAL' } }));
       expect(component.canAccessComments()).toBe(false);
     });
+
+    it('allows editing public notice only when FOM is INITIAL and user is authorized', async () => {
+      await createComponent(project({ workflowState: { code: 'INITIAL' } }));
+      expect(component.canEditPublicNotice()).toBe(true);
+
+      component.user.isAuthorizedForClientId = () => false;
+      expect(component.canEditPublicNotice()).toBe(false);
+
+      component.user.isAuthorizedForClientId = () => true;
+      await createComponent(project({ workflowState: { code: 'PUBLISHED' } }));
+      expect(component.canEditPublicNotice()).toBe(false);
+    });
+
+    it('allows viewing public notice for authorized client or ministry user regardless of workflow state', async () => {
+      await createComponent(project({ workflowState: { code: 'INITIAL', publicNoticeId: undefined } }));
+      expect(component.canViewPublicNotice()).toBe(true);
+
+      await createComponent(project({ workflowState: { code: 'PUBLISHED', publicNoticeId: 55 } }));
+      expect(component.canViewPublicNotice()).toBe(true);
+
+      component.user.isAuthorizedForClientId = () => false;
+      component.user.isMinistry = false;
+      expect(component.canViewPublicNotice()).toBe(false);
+    });
+  });
+
+  describe('zero-state FOM without public notice', () => {
+    it('renders project detail safely when publicNoticeId is undefined', async () => {
+      await createComponent(project({ publicNoticeId: undefined, workflowState: { code: 'INITIAL' } }));
+      expect(component.project().publicNoticeId).toBeUndefined();
+      expect(fixture.nativeElement.textContent).toContain('Test FOM Holder');
+    });
   });
 });

api/package.json

@@ -16,10 +16,10 @@
     "db:migrate-test:revert": "npm run typeorm migration:revert -- -f ./src/migrations/ormconfig-migration-test.ts",
     "db:migrate-test:show": "npm run typeorm migration:show -- -f ./src/migrations/ormconfig-migration-test.ts",
     "perf-test:gen-data": "node src/perftest/generate-data.js",
-    "test-unit": "set LOG_LEVEL=warn && jest --coverage --testPathIgnorePatterns='e2e'",
-    "test-unit-watch": "set LOG_LEVEL=warn && jest --testPathIgnorePatterns='e2e' --watch=true",
-    "test-e2e": "set LOG_LEVEL=warn && jest --testNamePattern='e2e'",
-    "test:cov": "jest --coverage"
+    "test-unit": "LOG_LEVEL=warn jest --coverage --maxWorkers=2 --testPathIgnorePatterns='e2e'",
+    "test-unit-watch": "LOG_LEVEL=warn jest --testPathIgnorePatterns='e2e' --watch=true --maxWorkers=2",
+    "test-e2e": "LOG_LEVEL=warn jest --testNamePattern='e2e' --maxWorkers=2",
+    "test:cov": "LOG_LEVEL=warn jest --coverage --maxWorkers=2"
   },
   "private": true,
   "engines": {

api/src/app/modules/project/project.service.spec.ts

@@ -206,6 +206,20 @@ describe('ProjectService', () => {
         expect(districtSpy).toHaveBeenCalledWith(entity.districtId);
         expect(postdateOnOrBeforeCommentingOpenDateSpy).not.toHaveBeenCalled();
       });
+
+      it('with empty array publicNotices pass', async () => {
+        entity.commentingOpenDate = dayjs.tz(DateTimeUtil.nowBC().add(1, 'day'), DateTimeUtil.TIMEZONE_VANCOUVER).format(DateTimeUtil.DATE_FORMAT);
+        entity.commentingClosedDate = dayjs.tz(entity.commentingOpenDate, DateTimeUtil.TIMEZONE_VANCOUVER)
+            .add(closeDateAfterOpeningDateDays, 'day')
+            .format(DateTimeUtil.DATE_FORMAT);
+        entity.publicNotices = []; // empty array public-notice.
+
+        await service.validateWorkflowTransitionRules(entity as Project, stateTransition, user);
+
+        expect(districtSpy).toHaveBeenCalled();
+        expect(districtSpy).toHaveBeenCalledWith(entity.districtId);
+        expect(postdateOnOrBeforeCommentingOpenDateSpy).not.toHaveBeenCalled();
+      });
 
       it('with public-notice and no post_date pass', async () => {
         entity.commentingOpenDate = dayjs.tz(DateTimeUtil.nowBC().add(1, 'day'), DateTimeUtil.TIMEZONE_VANCOUVER).format(DateTimeUtil.DATE_FORMAT);

package.json

@@ -18,7 +18,10 @@
     "build:api": "npm run build:api --workspace=api",
     "start:public": "npm run start:public --workspace=public",
     "start:admin": "npm run start:admin --workspace=admin",
-    "start:api": "npm run start:api --workspace=api"
+    "start:api": "npm run start:api --workspace=api",
+    "test:public": "npm run test-unit --workspace=public",
+    "test:admin": "npm run test-unit --workspace=admin",
+    "test:api": "npm run test-unit --workspace=api"
   },
   "overrides": {
     "ngx-bootstrap": {

public/package.json

@@ -5,8 +5,8 @@
   "scripts": {
     "start:public": "ng serve --configuration development --host=0.0.0.0",
     "build:public": "ng build --configuration production",
-    "test-unit": "jest --coverage",
-    "test-unit-watch": "jest --watch=true"
+    "test-unit": "jest --coverage --maxWorkers=2",
+    "test-unit-watch": "jest --watch=true --maxWorkers=2"
   },
   "private": true,
   "engines": {