@qball-inc/the-bulwark 1.0.0

package/skills/code-review/examples/recommended/standards.ts

@@ -0,0 +1,231 @@
+/**
+ * Coding Standards Recommended Patterns
+ *
+ * These examples demonstrate good coding standards.
+ */
+
+// CS1: Single Responsibility - Each function does one thing
+async function validateOrder(order: Order): Promise<void> {
+  if (!order.items.length) {
+    throw new OrderValidationError('Empty order');
+  }
+}
+
+function calculateOrderTotal(order: Order): number {
+  return order.items.reduce((sum, item) => sum + item.price, 0);
+}
+
+async function saveOrder(order: Order): Promise<void> {
+  await database.orders.save(order);
+}
+
+async function notifyOrderConfirmation(order: Order): Promise<void> {
+  await emailService.send(order.customer.email, 'Order confirmed');
+}
+
+async function trackOrderProcessed(order: Order): Promise<void> {
+  await analytics.track('order_processed', order.id);
+}
+
+// Composition of single-responsibility functions
+async function processOrderClean(order: Order): Promise<Order> {
+  await validateOrder(order);
+  order.total = calculateOrderTotal(order);
+  await saveOrder(order);
+  await notifyOrderConfirmation(order);
+  await trackOrderProcessed(order);
+  return order;
+}
+
+// CS2: Named Constants - No Magic Values
+const DISCOUNT_THRESHOLDS = {
+  MINIMUM_FOR_DISCOUNT: 100,
+} as const;
+
+const DISCOUNT_RATES = {
+  GOLD: 0.2,
+  SILVER: 0.1,
+  DEFAULT: 0.05,
+} as const;
+
+type CustomerType = 'gold' | 'silver' | 'bronze';
+
+function calculateDiscountClean(total: number, customerType: CustomerType): number {
+  if (total <= DISCOUNT_THRESHOLDS.MINIMUM_FOR_DISCOUNT) {
+    return total * DISCOUNT_RATES.DEFAULT;
+  }
+
+  const rate = customerType === 'gold'
+    ? DISCOUNT_RATES.GOLD
+    : customerType === 'silver'
+    ? DISCOUNT_RATES.SILVER
+    : DISCOUNT_RATES.DEFAULT;
+
+  return total * rate;
+}
+
+// CS2: Explicit Transformation - Return new object instead of mutation
+function normalizeUserClean(user: User): NormalizedUser {
+  return {
+    ...user,
+    email: user.email.toLowerCase(),
+    name: user.name.trim(),
+    normalizedAt: new Date(),
+  };
+}
+
+// CS2: Explicit Dependencies - Pass state as parameter
+interface Transaction {
+  id: string;
+  amount: number;
+  status: 'pending' | 'processing' | 'completed';
+}
+
+function processPaymentClean(
+  transaction: Transaction,
+  amount: number
+): Transaction {
+  return {
+    ...transaction,
+    amount,
+    status: 'processing',
+  };
+}
+
+// CS2: Pure Getters - No side effects
+class UserProfileClean {
+  private _views = 0;
+  private readonly id: string;
+
+  get viewCount(): number {
+    return this._views;
+  }
+
+  // Side effect is explicit method, not hidden in getter
+  recordView(): void {
+    this._views++;
+  }
+
+  // Analytics tracking is separate concern
+  trackProfileView(): void {
+    analytics.track('profile_viewed', this.id);
+  }
+}
+
+// CS3: Fail Fast - Propagate errors with context
+async function fetchDataClean(id: string): Promise<Data> {
+  try {
+    return await api.getData(id);
+  } catch (error) {
+    // Log for debugging
+    console.error(`Failed to fetch data for id=${id}:`, error);
+    // Re-throw with context
+    throw new DataFetchError(`Failed to fetch data: ${id}`, { cause: error });
+  }
+}
+
+// CS3: Fail on Invalid Input
+function parseConfigClean(raw: string): Config {
+  try {
+    const parsed = JSON.parse(raw);
+    return validateConfig(parsed);
+  } catch (error) {
+    throw new ConfigParseError('Invalid configuration', { cause: error });
+  }
+}
+
+// CS3: Input Validation at Boundaries
+function calculateAgeClean(birthYear: number): number {
+  const currentYear = new Date().getFullYear();
+
+  if (!Number.isInteger(birthYear)) {
+    throw new ValidationError('Birth year must be an integer');
+  }
+  if (birthYear < 1900) {
+    throw new ValidationError('Birth year too far in the past');
+  }
+  if (birthYear > currentYear) {
+    throw new ValidationError('Birth year cannot be in the future');
+  }
+
+  return currentYear - birthYear;
+}
+
+// CS4: Clean Imports - Only import what's used
+import { neededHelper } from './utils';
+import type { Config, Data } from './types';
+
+// CS4: All Variables Used
+function processItemsClean(items: Item[]): string[] {
+  // Only declare what's needed
+  return items.map((item) => item.name);
+}
+
+// CS4: No Commented-Out Code - Delete unused code
+function handleRequestClean(req: Request) {
+  // Old implementation deleted, not commented
+  return processNewWay(req);
+}
+
+// CS4: No Dead Code - All paths reachable
+function processClean(value: number): number {
+  if (value > 0) {
+    return value * 2;
+  }
+  return value;
+}
+
+/**
+ * Calculate a complex weighted metric from data points.
+ *
+ * @param data - Array of metric data points to analyze
+ * @param weights - Weight for each data point (must match data length)
+ * @param normalize - Whether to normalize the result to 0-1 range
+ * @param threshold - Minimum value to include in calculation
+ * @returns Calculated metric with metadata
+ *
+ * @example
+ * ```typescript
+ * const result = calculateComplexMetric(
+ *   [{ value: 10 }, { value: 20 }],
+ *   [0.3, 0.7],
+ *   true,
+ *   5
+ * );
+ * ```
+ */
+export function calculateComplexMetricClean(
+  data: MetricData[],
+  weights: number[],
+  normalize: boolean,
+  threshold: number
+): ComplexResult {
+  validateInputs(data, weights, threshold);
+  return internalCalculation(data, weights, normalize, threshold);
+}
+
+// Consistent Error Handling
+async function fetchAllClean(): Promise<FetchResult> {
+  // Consistent try-catch for all operations
+  try {
+    const [users, orders, products] = await Promise.all([
+      fetch('/users').then((r) => r.json()),
+      fetch('/orders').then((r) => r.json()),
+      fetch('/products').then((r) => r.json()),
+    ]);
+
+    return { users, orders, products, success: true };
+  } catch (error) {
+    console.error('Failed to fetch data:', error);
+    throw new DataFetchError('Failed to load data', { cause: error });
+  }
+}
+
+// Consistent Async Style
+async function loadDataClean(): Promise<ProcessedData> {
+  // Consistent await throughout
+  const config = await loadConfig();
+  const response = await fetch(config.url);
+  const data = await response.json();
+  return processData(data);
+}

package/skills/code-review/examples/recommended/type-safety.ts

@@ -0,0 +1,181 @@
+/**
+ * Type Safety Recommended Patterns
+ *
+ * These examples demonstrate type-safe coding practices.
+ */
+
+// Proper typing instead of `any`
+interface ProcessableData {
+  id: string;
+  payload: Record<string, unknown>;
+}
+
+function processDataSafe(data: ProcessableData) {
+  // Type-safe access
+  return data.payload;
+}
+
+// Typed return with proper interface
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+async function fetchUserSafe(id: string): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  const data = await response.json();
+
+  // Validate shape before returning
+  if (!isUser(data)) {
+    throw new Error('Invalid user data');
+  }
+  return data;
+}
+
+// Type guard for runtime validation
+function isUser(data: unknown): data is User {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'id' in data &&
+    'name' in data &&
+    'email' in data
+  );
+}
+
+// JSON parsing with validation
+import { z } from 'zod';
+
+const ConfigSchema = z.object({
+  apiUrl: z.string().url(),
+  timeout: z.number().positive(),
+});
+
+type Config = z.infer<typeof ConfigSchema>;
+
+function loadConfigSafe(): Config {
+  const raw = JSON.parse(process.env.CONFIG ?? '{}');
+  return ConfigSchema.parse(raw); // Throws if invalid
+}
+
+// Explicit parameter types
+function calculateSafe(a: number, b: number): number {
+  return a + b;
+}
+
+// Safe null handling with type narrowing
+interface UserProfile {
+  name: string;
+  profile?: {
+    avatar?: string;
+  };
+}
+
+function getAvatarSafe(user: UserProfile | null): string {
+  if (!user) {
+    return 'default-avatar.png';
+  }
+  return user.profile?.avatar ?? 'default-avatar.png';
+}
+
+// Consistent optional chaining
+function getNameSafe(user: UserProfile | null): string {
+  // All access uses optional chaining consistently
+  return user?.profile?.avatar ?? 'default';
+}
+
+// Nullish coalescing for valid falsy values
+function getCountSafe(items?: number): number {
+  // Uses ?? to only default on null/undefined, not 0
+  return items ?? 10;
+}
+
+// Type narrowing instead of assertion
+function convertSafe(value: string): number {
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed)) {
+    throw new Error(`Cannot convert "${value}" to number`);
+  }
+  return parsed;
+}
+
+// Type guard for API responses
+interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+
+function parseResponseSafe<T>(
+  response: ApiResponse<T>,
+  guard: (data: unknown) => data is T
+): T {
+  if (!response.success || !response.data) {
+    throw new Error(response.error ?? 'Request failed');
+  }
+
+  if (!guard(response.data)) {
+    throw new Error('Invalid response shape');
+  }
+
+  return response.data;
+}
+
+// Safe array access with validation
+async function getFirstUserSafe(): Promise<User> {
+  const users = await fetchUsers();
+
+  if (users.length === 0) {
+    throw new Error('No users found');
+  }
+
+  return users[0]; // Now guaranteed to exist
+}
+
+// Typed catch clause
+async function fetchDataSafe() {
+  try {
+    return await fetch('/api/data');
+  } catch (error) {
+    if (error instanceof Error) {
+      console.log(error.message);
+    } else {
+      console.log('Unknown error:', error);
+    }
+  }
+}
+
+// Proper generic constraints
+interface Identifiable {
+  id: string;
+}
+
+function wrapSafe<T extends Identifiable>(value: T): { wrapped: T; id: string } {
+  return { wrapped: value, id: value.id };
+}
+
+// Discriminated unions for exhaustive checking
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+function handleResult<T>(result: Result<T>): T {
+  if (result.success) {
+    return result.data;
+  }
+  throw new Error(result.error);
+}
+
+// Branded types for semantic safety
+type UserId = string & { readonly __brand: 'UserId' };
+type OrderId = string & { readonly __brand: 'OrderId' };
+
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+function getUserById(id: UserId): Promise<User> {
+  // Can only be called with UserId, not OrderId
+  return fetch(`/api/users/${id}`).then((r) => r.json());
+}

package/skills/code-review/frameworks/angular.md

@@ -0,0 +1,218 @@
+# Angular Framework Patterns
+
+Security and quality patterns specific to Angular applications.
+
+---
+
+## Security Patterns
+
+### XSS Prevention
+
+| Pattern | Risk | Detection |
+|---------|------|-----------|
+| `innerHTML` binding | High | `[innerHTML]="userInput"` without sanitization |
+| `bypassSecurityTrust*` | Critical | Bypassing Angular sanitizer |
+| Template injection | High | Dynamic template construction |
+
+**Safe Pattern:**
+```typescript
+// BAD
+@Component({
+  template: `<div [innerHTML]="userComment"></div>`
+})
+
+// GOOD - Angular sanitizes by default for interpolation
+@Component({
+  template: `<div>{{userComment}}</div>`
+})
+
+// If HTML is needed, sanitize explicitly
+import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
+
+@Component({
+  template: `<div [innerHTML]="sanitizedContent"></div>`
+})
+export class CommentComponent {
+  sanitizedContent: SafeHtml;
+
+  constructor(private sanitizer: DomSanitizer) {}
+
+  setContent(html: string) {
+    // Only use when HTML is from trusted source
+    this.sanitizedContent = this.sanitizer.sanitize(SecurityContext.HTML, html);
+  }
+}
+```
+
+### URL Safety
+
+| Pattern | Risk | Detection |
+|---------|------|-----------|
+| Dynamic href | High | `[href]="userUrl"` |
+| Router navigate with user input | Medium | `router.navigate([userInput])` |
+
+**Safe Pattern:**
+```typescript
+// Validate URLs before using
+validateUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return ['http:', 'https:'].includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+}
+```
+
+### HTTP Security
+
+```typescript
+// Always use HttpClient (includes XSRF protection)
+import { HttpClient } from '@angular/common/http';
+
+// Configure XSRF
+@NgModule({
+  imports: [
+    HttpClientModule,
+    HttpClientXsrfModule.withOptions({
+      cookieName: 'XSRF-TOKEN',
+      headerName: 'X-XSRF-TOKEN'
+    })
+  ]
+})
+```
+
+---
+
+## Type Safety Patterns
+
+### Component Inputs/Outputs
+
+```typescript
+// BAD
+@Input() data: any;
+@Output() changed = new EventEmitter<any>();
+
+// GOOD
+interface UserData {
+  id: string;
+  name: string;
+}
+
+@Input() data!: UserData;
+@Output() changed = new EventEmitter<UserData>();
+```
+
+### Observable Typing
+
+```typescript
+// BAD
+users$: Observable<any>;
+
+// GOOD
+users$: Observable<User[]>;
+
+// With error handling
+users$ = this.http.get<User[]>('/api/users').pipe(
+  catchError(error => {
+    console.error('Failed to fetch users:', error);
+    return of([]);
+  })
+);
+```
+
+### Form Typing
+
+```typescript
+// BAD
+form = new FormGroup({
+  name: new FormControl(''),
+  email: new FormControl('')
+});
+
+// GOOD - Typed forms (Angular 14+)
+interface UserForm {
+  name: FormControl<string>;
+  email: FormControl<string>;
+}
+
+form = new FormGroup<UserForm>({
+  name: new FormControl('', { nonNullable: true }),
+  email: new FormControl('', { nonNullable: true })
+});
+```
+
+---
+
+## Linting Patterns
+
+### Component Size
+
+| Metric | Threshold | Action |
+|--------|-----------|--------|
+| Template lines | >100 | Split to sub-components |
+| Component methods | >10 | Extract to service |
+| Constructor params | >5 | Review dependencies |
+
+### Subscription Management
+
+```typescript
+// BAD - Memory leak
+ngOnInit() {
+  this.service.getData().subscribe(data => this.data = data);
+}
+
+// GOOD - Automatic cleanup
+data$ = this.service.getData();
+// Use async pipe in template: {{ data$ | async }}
+
+// Or manual cleanup
+private destroy$ = new Subject<void>();
+
+ngOnInit() {
+  this.service.getData()
+    .pipe(takeUntil(this.destroy$))
+    .subscribe(data => this.data = data);
+}
+
+ngOnDestroy() {
+  this.destroy$.next();
+  this.destroy$.complete();
+}
+```
+
+---
+
+## Coding Standards
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Component | PascalCase + Component suffix | `UserProfileComponent` |
+| Service | PascalCase + Service suffix | `AuthService` |
+| Directive | PascalCase + Directive suffix | `HighlightDirective` |
+| Pipe | PascalCase + Pipe suffix | `CurrencyPipe` |
+
+### File Organization
+
+```
+feature/
+  feature.component.ts
+  feature.component.html
+  feature.component.scss
+  feature.component.spec.ts
+  feature.module.ts
+  feature-routing.module.ts
+  services/
+  models/
+```
+
+---
+
+## What to Skip
+
+- Angular CLI generated code
+- Zone.js related patterns
+- Test bed setup boilerplate
+- Module declarations