@malamute/ai-rules 1.0.0

package/configs/angular/.claude/rules/components.md

@@ -0,0 +1,257 @@
+---
+paths:
+  - "libs/**/feature/**/*.ts"
+  - "libs/**/ui/**/*.ts"
+  - "apps/**/*.component.ts"
+---
+
+# Component Rules (Angular 21)
+
+## Code Quality
+
+### No Useless Comments
+
+Code must be self-documenting. Variable and function names must be explicit.
+
+```typescript
+// BAD
+const c = getConfig();  // get the config
+items.filter(x => x.active);
+
+// GOOD
+const applicationConfig = getConfig();
+items.filter(item => item.active);
+users.map(user => user.email);
+```
+
+### Never Disable Lint Rules Without Justification
+
+```typescript
+// FORBIDDEN - no explanation
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+// ALLOWED - only with explicit justification
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Third-party API returns untyped response, ticket ABC-123 to add types
+```
+
+### ChangeDetectionStrategy.OnPush
+
+Use `OnPush` for performance optimization. Required for:
+- All UI components (dumb components)
+- Feature components with signal-based state
+- Any component where you control the inputs
+
+```typescript
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,  // Always add this
+})
+```
+
+## File Structure
+
+Always use separate files for template and styles:
+
+```
+user-list/
+  user-list.component.ts
+  user-list.component.html
+  user-list.component.scss
+  user-list.component.spec.ts
+```
+
+## @Component Decorator
+
+```typescript
+@Component({
+  selector: 'app-user-list',
+  imports: [SomeComponent, SomePipe],         // Direct imports
+  templateUrl: './user-list.component.html',  // Always external
+  styleUrl: './user-list.component.scss',     // Always external
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+```
+
+**Do NOT include:**
+- `standalone: true` (it's the default)
+- `template:` inline templates
+- `styles:` inline styles
+
+## Smart Components (feature/)
+
+Smart components are located in `feature/` libraries.
+
+### Allowed
+
+- Inject `Store` from NgRx
+- Dispatch actions
+- Use `selectSignal()` for state
+- Handle routing and navigation
+- Contain page-level logic
+
+### Required
+
+- Pass data to UI components via `input()` signals
+- Handle events from UI components via `output()`
+- Use `ChangeDetectionStrategy.OnPush`
+- Use `templateUrl` (external template file)
+
+### Example
+
+```typescript
+// product-page.component.ts
+@Component({
+  selector: 'app-product-page',
+  imports: [ProductListComponent, ProductFiltersComponent],
+  templateUrl: './product-page.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ProductPageComponent {
+  private readonly store = inject(Store);
+
+  categories = this.store.selectSignal(selectCategories);
+  filteredProducts = this.store.selectSignal(selectFilteredProducts);
+  loading = this.store.selectSignal(selectProductsLoading);
+
+  onFilterChange(filters: Filters): void {
+    this.store.dispatch(ProductActions.setFilters({ filters }));
+  }
+
+  onAddToCart(product: Product): void {
+    this.store.dispatch(CartActions.addItem({ product }));
+  }
+}
+```
+
+```html
+<!-- product-page.component.html -->
+<app-product-filters
+  [categories]="categories()"
+  (filterChange)="onFilterChange($event)"
+/>
+
+<app-product-list
+  [products]="filteredProducts()"
+  [loading]="loading()"
+  (addToCart)="onAddToCart($event)"
+/>
+```
+
+## UI Components (ui/)
+
+UI components are located in `ui/` libraries. They are purely presentational.
+
+### Forbidden
+
+- NO `Store` injection
+- NO service injection (except pure utility services)
+- NO direct HTTP calls
+- NO router navigation
+- NO business logic
+
+### Required
+
+- Use `input()` and `input.required()` for data
+- Use `output()` for events
+- Use `model()` for two-way binding
+- Use `ChangeDetectionStrategy.OnPush`
+- Must be fully testable in isolation
+
+### Example
+
+```typescript
+// product-card.component.ts
+@Component({
+  selector: 'app-product-card',
+  imports: [CurrencyPipe],
+  templateUrl: './product-card.component.html',
+  styleUrl: './product-card.component.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ProductCardComponent {
+  product = input.required<Product>();
+  addToCart = output<Product>();
+}
+```
+
+```html
+<!-- product-card.component.html -->
+<article class="product-card">
+  <img [src]="product().image" [alt]="product().name" />
+  <h3>{{ product().name }}</h3>
+  <p class="price">{{ product().price | currency }}</p>
+  <button type="button" (click)="addToCart.emit(product())">
+    Add to Cart
+  </button>
+</article>
+```
+
+## Signal Inputs/Outputs/Model
+
+Always use signal-based functions, NOT decorators:
+
+```typescript
+// Inputs - use input(), NOT @Input()
+name = input<string>();              // Optional
+name = input('default');             // With default
+name = input.required<string>();     // Required
+
+// Outputs - use output(), NOT @Output()
+clicked = output<void>();
+selected = output<Item>();
+
+// Two-way binding - use model()
+value = model<string>('');           // Optional with default
+value = model.required<string>();    // Required
+
+// Emit
+this.clicked.emit();
+this.selected.emit(item);
+this.value.set('new value');         // model is writable
+```
+
+### Two-way Binding with model()
+
+```typescript
+// Component
+@Component({
+  selector: 'app-search-input',
+  templateUrl: './search-input.component.html',
+})
+export class SearchInputComponent {
+  query = model('');  // Creates [(query)] binding
+}
+```
+
+```html
+<!-- Parent usage -->
+<app-search-input [(query)]="searchQuery" />
+```
+
+## Control Flow (in templates)
+
+Use the built-in control flow syntax:
+
+```html
+<!-- Conditionals -->
+@if (loading()) {
+  <app-spinner />
+} @else if (error()) {
+  <app-error [message]="error()" />
+} @else {
+  <app-content [data]="data()" />
+}
+
+<!-- Loops - always use track! -->
+@for (item of items(); track item.id) {
+  <app-item [item]="item" />
+} @empty {
+  <p>No items found</p>
+}
+
+<!-- Switch -->
+@switch (status()) {
+  @case ('loading') { <app-spinner /> }
+  @case ('error') { <app-error /> }
+  @default { <app-content /> }
+}
+```

package/configs/angular/.claude/rules/state.md

@@ -0,0 +1,250 @@
+---
+paths:
+  - "libs/**/data-access/**/*.ts"
+  - "libs/**/+state/**/*.ts"
+---
+
+# NgRx State Management Rules
+
+## File Structure
+
+```
+libs/[domain]/data-access/
+  src/lib/
+    +state/
+      [domain].actions.ts
+      [domain].reducer.ts
+      [domain].effects.ts
+      [domain].selectors.ts
+      [domain].adapter.ts      # If using @ngrx/entity
+      [domain].state.ts        # State interface
+    services/
+      [domain].service.ts      # API calls
+    index.ts                   # Public API
+```
+
+## Actions
+
+Use `createActionGroup` for related actions:
+
+```typescript
+import { createActionGroup, emptyProps, props } from '@ngrx/store';
+
+export const UserActions = createActionGroup({
+  source: 'Users',
+  events: {
+    // Load
+    'Load Users': emptyProps(),
+    'Load Users Success': props<{ users: User[] }>(),
+    'Load Users Failure': props<{ error: string }>(),
+
+    // CRUD
+    'Add User': props<{ user: User }>(),
+    'Update User': props<{ update: Update<User> }>(),
+    'Delete User': props<{ id: string }>(),
+
+    // Selection
+    'Select User': props<{ id: string }>(),
+    'Clear Selection': emptyProps(),
+  },
+});
+```
+
+## Reducer with Entity Adapter
+
+Always use `@ngrx/entity` for collections:
+
+```typescript
+// [domain].adapter.ts
+import { createEntityAdapter, EntityAdapter, EntityState } from '@ngrx/entity';
+
+export interface UserState extends EntityState<User> {
+  selectedId: string | null;
+  loading: boolean;
+  error: string | null;
+}
+
+export const userAdapter: EntityAdapter<User> = createEntityAdapter<User>({
+  selectId: (user) => user.id,
+  sortComparer: (a, b) => a.name.localeCompare(b.name),
+});
+
+export const initialUserState: UserState = userAdapter.getInitialState({
+  selectedId: null,
+  loading: false,
+  error: null,
+});
+```
+
+```typescript
+// [domain].reducer.ts
+import { createReducer, on } from '@ngrx/store';
+
+export const userReducer = createReducer(
+  initialUserState,
+
+  on(UserActions.loadUsers, (state) => ({
+    ...state,
+    loading: true,
+    error: null,
+  })),
+
+  on(UserActions.loadUsersSuccess, (state, { users }) =>
+    userAdapter.setAll(users, { ...state, loading: false })
+  ),
+
+  on(UserActions.loadUsersFailure, (state, { error }) => ({
+    ...state,
+    loading: false,
+    error,
+  })),
+
+  on(UserActions.addUser, (state, { user }) =>
+    userAdapter.addOne(user, state)
+  ),
+
+  on(UserActions.updateUser, (state, { update }) =>
+    userAdapter.updateOne(update, state)
+  ),
+
+  on(UserActions.deleteUser, (state, { id }) =>
+    userAdapter.removeOne(id, state)
+  ),
+
+  on(UserActions.selectUser, (state, { id }) => ({
+    ...state,
+    selectedId: id,
+  })),
+
+  on(UserActions.clearSelection, (state) => ({
+    ...state,
+    selectedId: null,
+  }))
+);
+```
+
+## Selectors
+
+Use adapter selectors and compose them:
+
+```typescript
+// [domain].selectors.ts
+import { createFeatureSelector, createSelector } from '@ngrx/store';
+
+// Feature selector
+export const selectUserState = createFeatureSelector<UserState>('users');
+
+// Adapter selectors
+const { selectAll, selectEntities, selectIds, selectTotal } =
+  userAdapter.getSelectors();
+
+// Exported selectors
+export const selectAllUsers = createSelector(selectUserState, selectAll);
+
+export const selectUserEntities = createSelector(selectUserState, selectEntities);
+
+export const selectUsersLoading = createSelector(
+  selectUserState,
+  (state) => state.loading
+);
+
+export const selectUsersError = createSelector(
+  selectUserState,
+  (state) => state.error
+);
+
+export const selectSelectedUserId = createSelector(
+  selectUserState,
+  (state) => state.selectedId
+);
+
+export const selectSelectedUser = createSelector(
+  selectUserEntities,
+  selectSelectedUserId,
+  (entities, selectedId) => (selectedId ? entities[selectedId] : null)
+);
+
+// Derived/computed selectors
+export const selectActiveUsers = createSelector(
+  selectAllUsers,
+  (users) => users.filter((u) => u.active)
+);
+
+export const selectUserCount = createSelector(
+  selectUserState,
+  selectTotal
+);
+```
+
+## Effects
+
+Keep effects clean and focused:
+
+```typescript
+// [domain].effects.ts
+import { inject } from '@angular/core';
+import { Actions, createEffect, ofType } from '@ngrx/effects';
+import { catchError, exhaustMap, map, of } from 'rxjs';
+
+export const loadUsers$ = createEffect(
+  (actions$ = inject(Actions), userService = inject(UserService)) =>
+    actions$.pipe(
+      ofType(UserActions.loadUsers),
+      exhaustMap(() =>
+        userService.getAll().pipe(
+          map((users) => UserActions.loadUsersSuccess({ users })),
+          catchError((error) =>
+            of(UserActions.loadUsersFailure({ error: error.message }))
+          )
+        )
+      )
+    ),
+  { functional: true }
+);
+
+export const addUser$ = createEffect(
+  (actions$ = inject(Actions), userService = inject(UserService)) =>
+    actions$.pipe(
+      ofType(UserActions.addUser),
+      exhaustMap(({ user }) =>
+        userService.create(user).pipe(
+          map((created) => UserActions.addUserSuccess({ user: created })),
+          catchError((error) =>
+            of(UserActions.addUserFailure({ error: error.message }))
+          )
+        )
+      )
+    ),
+  { functional: true }
+);
+```
+
+## RxJS Operator Guidelines
+
+| Scenario | Operator |
+|----------|----------|
+| Single request, cancel previous | `switchMap` |
+| Single request, ignore while pending | `exhaustMap` |
+| Queue all requests | `concatMap` |
+| Parallel requests | `mergeMap` |
+
+## Store Usage in Components
+
+Only in smart components (feature/):
+
+```typescript
+// Use selectSignal for signal-based selection
+users = this.store.selectSignal(selectAllUsers);
+loading = this.store.selectSignal(selectUsersLoading);
+
+// Dispatch actions
+this.store.dispatch(UserActions.loadUsers());
+```
+
+## Anti-patterns to Avoid
+
+- Never store derived state in the store (use selectors)
+- Never dispatch actions from effects that trigger the same effect
+- Never use `store.select()` in UI components
+- Never mutate state directly
+- Avoid fat effects - keep business logic in services