front-end-dev-standards 1.0.0

package/standards/security.md

@@ -0,0 +1,6 @@
+# Security Standards
+
+> Placeholder — auto-discovered by setup.js when you run standards:setup.
+
+- Never commit secrets or API keys.
+- Use environment variables for sensitive config.

package/standards/testing.md

@@ -0,0 +1,244 @@
+# Testing Standards
+
+> Unit and integration testing conventions for Angular applications using Vitest.
+
+---
+
+## Test Stack
+
+| Tool | Purpose |
+|---|---|
+| **Vitest** | Test runner (Angular 21 default) |
+| **Angular TestBed** | Component/service integration |
+| **ng-mocks** / manual stubs | Dependency mocking (when needed) |
+
+Run tests:
+
+```bash
+npm test
+ng test
+```
+
+---
+
+## File Conventions
+
+- Co-locate tests: `employee.service.ts` → `employee.service.spec.ts`
+- Page tests: `employee-list.page.spec.ts`
+- Place test utilities in `src/testing/` or feature `testing/` folder.
+
+---
+
+## Service Tests
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { provideHttpClient } from '@angular/common/http';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { EmployeeService } from './employee.service';
+
+describe('EmployeeService', () => {
+  let service: EmployeeService;
+  let httpMock: HttpTestingController;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [EmployeeService, provideHttpClient(), provideHttpClientTesting()],
+    });
+
+    service = TestBed.inject(EmployeeService);
+    httpMock = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    httpMock.verify();
+  });
+
+  it('should fetch all employees', () => {
+    const mockEmployees = [{ id: '1', firstName: 'Jane', lastName: 'Doe', email: 'jane@co.com', departmentId: 'd1', createdAt: '2024-01-01' }];
+
+    service.getAll().subscribe(employees => {
+      expect(employees).toEqual(mockEmployees);
+    });
+
+    const req = httpMock.expectOne('/api/employees');
+    expect(req.request.method).toBe('GET');
+    req.flush(mockEmployees);
+  });
+});
+```
+
+### Service Test Rules
+
+- Use `HttpTestingController` for HTTP services.
+- Test success and error paths.
+- Verify request method, URL, headers, and body.
+- No real HTTP calls in unit tests.
+
+---
+
+## Component Tests
+
+```typescript
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+import { EmployeeListPage } from './employee-list.page';
+import { EmployeeService } from '../../services/employee.service';
+import { of, throwError } from 'rxjs';
+
+describe('EmployeeListPage', () => {
+  let fixture: ComponentFixture<EmployeeListPage>;
+  let component: EmployeeListPage;
+  let employeeService: { getAll: ReturnType<typeof vi.fn> };
+
+  beforeEach(async () => {
+    employeeService = { getAll: vi.fn().mockReturnValue(of([])) };
+
+    await TestBed.configureTestingModule({
+      imports: [EmployeeListPage],
+      providers: [{ provide: EmployeeService, useValue: employeeService }],
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(EmployeeListPage);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+
+  it('should display employees when loaded', () => {
+    const employees = [{ id: '1', firstName: 'Jane', lastName: 'Doe', email: 'j@co.com', departmentId: 'd1', createdAt: '2024-01-01' }];
+    employeeService.getAll.mockReturnValue(of(employees));
+
+    component.loadEmployees();
+    fixture.detectChanges();
+
+    expect(component.employees()).toEqual(employees);
+  });
+
+  it('should set error signal on failure', () => {
+    employeeService.getAll.mockReturnValue(throwError(() => new Error('Network error')));
+
+    component.loadEmployees();
+    fixture.detectChanges();
+
+    expect(component.error()).toBeTruthy();
+    expect(component.loading()).toBe(false);
+  });
+});
+```
+
+### Component Test Rules
+
+- Import standalone component in `TestBed.configureTestingModule({ imports: [...] })`.
+- Mock services — don't test service logic in component tests.
+- Test signal state, not internal implementation details.
+- Query DOM for user-visible behavior when testing templates.
+- Use `fixture.detectChanges()` after state updates.
+
+---
+
+## Testing Signals
+
+```typescript
+it('should compute filtered employees', () => {
+  component.employees.set([
+    { id: '1', firstName: 'Jane', /* ... */ },
+    { id: '2', firstName: 'John', /* ... */ },
+  ]);
+  component.searchTerm.set('Jane');
+
+  expect(component.filteredEmployees()).toHaveLength(1);
+  expect(component.filteredEmployees()[0].firstName).toBe('Jane');
+});
+```
+
+Prefer testing public signal values over private fields.
+
+---
+
+## Test Naming
+
+Use descriptive `it` blocks:
+
+```typescript
+// Good
+it('should disable submit button when form is invalid')
+it('should redirect to login when auth guard rejects unauthenticated user')
+
+// Bad
+it('should work')
+it('test submit')
+```
+
+Pattern: `should [expected behavior] when [condition]`
+
+---
+
+## Coverage Expectations
+
+| Layer | Minimum Coverage |
+|---|---|
+| Services (business/API) | 80%+ |
+| Utility functions | 90%+ |
+| Smart/Page components | 70%+ |
+| Presentational components | Key interactions covered |
+| Guards / Interceptors | 100% of branches |
+
+Focus on **behavior coverage**, not line-count gaming.
+
+---
+
+## What to Test
+
+### Always Test
+
+- Service HTTP calls (success + error)
+- Form validation logic
+- Guards and interceptors
+- Complex computed signals
+- User interactions (click, submit, navigation)
+
+### Skip or Minimize
+
+- Trivial getters with no logic
+- Third-party library internals
+- Static template text with no binding logic
+
+---
+
+## Test Data
+
+Create factories in `testing/factories/`:
+
+```typescript
+// testing/factories/employee.factory.ts
+import { Employee } from '../../features/employees/models/employee.model';
+
+export function createEmployee(overrides: Partial<Employee> = {}): Employee {
+  return {
+    id: 'emp-1',
+    firstName: 'Jane',
+    lastName: 'Doe',
+    email: 'jane.doe@company.com',
+    departmentId: 'dept-1',
+    createdAt: '2024-06-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+```
+
+---
+
+## Anti-Patterns
+
+- ❌ Testing implementation details (private methods)
+- ❌ Shared mutable state between tests
+- ❌ `setTimeout` without fakeAsync / vi.useFakeTimers
+- ❌ Snapshot testing for entire templates ( brittle )
+- ❌ E2E tests disguised as unit tests

package/templates/company.mdc.template

@@ -0,0 +1,92 @@
+---
+description: Company Angular frontend coding standards — enforced for all AI-generated and reviewed code
+alwaysApply: true
+---
+
+# Company Frontend Standards (front-end-dev-standards v{{STANDARDS_VERSION}})
+
+You are generating code for an enterprise Angular application. Follow these standards strictly.
+
+> Auto-generated by front-end-dev-standards on {{GENERATED_AT}}.
+> Do not edit this file manually unless your team owns custom overrides — use `.standardsrc.json` and re-run setup.
+
+## Standards Documents
+
+Read and apply ALL of the following standards files in the project:
+
+{{STANDARDS_PATHS}}
+
+When standards conflict, priority order is:
+1. `angular.md` (framework-specific rules)
+2. `architecture.md` (structure and patterns)
+3. `coding-style.md` (naming and formatting)
+4. `testing.md` (test requirements)
+
+## Mandatory Angular Patterns (Angular 20+)
+
+Always generate:
+
+- **Standalone components** — no `NgModule` for new code
+- **`inject()`** for dependency injection — never constructor injection
+- **Signals** — `signal()`, `computed()`, `input()`, `output()` for state and bindings
+- **`ChangeDetectionStrategy.OnPush`** on every component
+- **Typed Reactive Forms** — `FormGroup<T>` with `nonNullable: true`
+- **Angular Material** for UI components in enterprise apps
+- **Feature-based folder structure** — see `architecture.md`
+- **Native control flow** — `@if`, `@for`, `@switch` (not structural directives)
+- **`track` in `@for` loops**
+
+Never generate:
+
+- ❌ `NgModule` declarations
+- ❌ Constructor-based dependency injection
+- ❌ `@Input()` / `@Output()` decorators (use signal inputs/outputs)
+- ❌ `*ngIf`, `*ngFor`, `*ngSwitch`
+- ❌ `BehaviorSubject` for simple component-local state
+- ❌ Untyped forms or `any` without justification
+- ❌ Business logic in templates
+- ❌ Direct DOM manipulation
+
+## Architecture Quick Reference
+
+```
+src/app/
+  core/       → guards, interceptors, app-wide services
+  shared/     → reusable UI components (no feature imports)
+  features/   → lazy-loaded business features
+  layout/     → app shell
+```
+
+Each feature:
+
+```
+features/<name>/
+  components/   → presentational
+  pages/        → smart/routable containers
+  services/     → API integration
+  models/       → TypeScript interfaces
+  <name>.routes.ts
+```
+
+## Code Generation Checklist
+
+Before finishing any generated code, verify:
+
+1. Component is standalone with explicit `imports` array
+2. OnPush change detection is set
+3. Services use `inject()` and `providedIn: 'root'`
+4. HTTP calls are typed: `http.get<ResponseType>()`
+5. Errors are handled and surfaced to the user
+6. A co-located `*.spec.ts` file exists for services and pages
+7. File names use kebab-case; classes use PascalCase
+
+## Testing Requirements
+
+When generating services or page components, also generate Vitest tests:
+
+- Use `TestBed.configureTestingModule({ imports: [StandaloneComponent] })`
+- Mock dependencies with `vi.fn()`
+- Test success and error paths
+- Use `HttpTestingController` for HTTP services
+
+See `.ai-standards/testing.md` for full testing standards.

package/templates/copilot-instructions.md.template

@@ -0,0 +1,92 @@
+# GitHub Copilot Instructions
+
+> Auto-generated by front-end-dev-standards v{{STANDARDS_VERSION}} on {{GENERATED_AT}}.
+
+Follow the company Angular frontend standards defined in this repository.
+
+## Standards Location
+
+{{STANDARDS_PATHS}}
+
+Read these files before generating or suggesting code.
+
+## Required Patterns (Angular 20+)
+
+When generating Angular code, ALWAYS use:
+
+- Standalone components (no NgModules)
+- `inject()` instead of constructor injection
+- Signals: `signal()`, `computed()`, `input()`, `output()`
+- `ChangeDetectionStrategy.OnPush`
+- Typed Reactive Forms with `FormGroup<T>` and `nonNullable: true`
+- Angular Material for UI
+- Native control flow: `@if`, `@for`, `@switch`
+- `track` expression in all `@for` loops
+- Feature-based architecture under `src/app/features/`
+
+## Never Suggest
+
+- NgModule-based components or declarations
+- Constructor dependency injection
+- `@Input()` / `@Output()` decorators (use signal-based APIs)
+- `*ngIf`, `*ngFor`, `*ngSwitch` structural directives
+- `BehaviorSubject` for simple UI state
+- Untyped forms or `any` type
+- Template-driven forms for complex forms
+- Direct DOM access (`document.querySelector`, `ElementRef` manipulation)
+
+## File Structure
+
+When creating new features:
+
+```
+src/app/features/<feature-name>/
+  components/       # presentational components
+  pages/            # routable smart components (*.page.ts)
+  services/         # API services
+  models/           # TypeScript interfaces
+  <feature>.routes.ts
+```
+
+## Naming Conventions
+
+- Files: `kebab-case` (e.g., `employee-list.component.ts`)
+- Classes: `PascalCase` (e.g., `EmployeeListComponent`)
+- Selectors: `app-` prefix (e.g., `app-employee-list`)
+- Signals: descriptive nouns (`employees`, `loading`, `isValid`)
+
+## Testing
+
+When suggesting tests, use Vitest with Angular TestBed:
+
+- Co-locate: `*.spec.ts` next to source file
+- Import standalone components in TestBed
+- Mock services with `vi.fn()`
+- Use `HttpTestingController` for HTTP testing
+
+## Example Component
+
+```typescript
+import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';
+import { EmployeeService } from '../services/employee.service';
+import { Employee } from '../models/employee.model';
+
+@Component({
+  selector: 'app-employee-list',
+  imports: [],
+  templateUrl: './employee-list.component.html',
+  styleUrl: './employee-list.component.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class EmployeeListComponent {
+  private readonly employeeService = inject(EmployeeService);
+
+  readonly employees = signal<Employee[]>([]);
+  readonly loading = signal(false);
+}
+```
+
+## Priority
+
+If unsure, prefer simpler signal-based standalone code over RxJS-heavy patterns.
+Always match existing project conventions in neighboring files.