@qball-inc/the-bulwark 1.0.0

package/skills/code-review/examples/anti-patterns/standards.ts

@@ -0,0 +1,195 @@
+/**
+ * Coding Standards Anti-Patterns
+ *
+ * DO NOT use these patterns in production code.
+ * Each example violates coding standards.
+ */
+
+// CS1: Multiple Responsibilities
+// BAD: Function does validation, transformation, persistence, AND notification
+async function processOrderViolation(order: Order) {
+  // Validate
+  if (!order.items.length) throw new Error('Empty order');
+
+  // Transform
+  order.total = order.items.reduce((sum, i) => sum + i.price, 0);
+
+  // Persist
+  await database.orders.save(order);
+
+  // Notify
+  await emailService.send(order.customer.email, 'Order confirmed');
+
+  // Track
+  await analytics.track('order_processed', order.id);
+
+  return order;
+}
+
+// CS2: Magic Values
+// BAD: Hardcoded values without explanation
+function calculateDiscountViolation(total: number, customerType: string): number {
+  if (total > 100) {
+    if (customerType === 'gold') {
+      return total * 0.2;
+    } else if (customerType === 'silver') {
+      return total * 0.1;
+    }
+  }
+  return total * 0.05;
+}
+
+// CS2: Hidden Mutation
+// BAD: Function modifies input object without indicating it
+function normalizeUserViolation(user: User) {
+  user.email = user.email.toLowerCase();
+  user.name = user.name.trim();
+  user.createdAt = new Date();
+  // Returns void but mutated input
+}
+
+// CS2: Implicit Global State
+// BAD: Function depends on undeclared global
+let currentTransaction: Transaction;
+
+function processPaymentViolation(amount: number) {
+  // Uses global state without indicating dependency
+  currentTransaction.amount = amount;
+  currentTransaction.status = 'processing';
+}
+
+// CS2: Side Effect in Getter
+// BAD: Property access triggers external action
+class UserProfileViolation {
+  private _views = 0;
+
+  get viewCount(): number {
+    // Side effect: logs to analytics
+    analytics.track('profile_viewed', this.id);
+    this._views++;
+    return this._views;
+  }
+}
+
+// CS3: Silent Failure
+// BAD: Catches and swallows error
+async function fetchDataViolation(id: string) {
+  try {
+    return await api.getData(id);
+  } catch (error) {
+    // Silent failure - no logging, no re-throw
+    return null;
+  }
+}
+
+// CS3: Default on Error
+// BAD: Returns default instead of failing
+function parseConfigViolation(raw: string): Config {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    // Returns invalid default, masking the error
+    return { apiUrl: 'http://localhost', timeout: 5000 };
+  }
+}
+
+// CS3: Missing Input Validation
+// BAD: Public function without validation
+function calculateAgeViolation(birthYear: number): number {
+  // No validation - negative years, future years accepted
+  return new Date().getFullYear() - birthYear;
+}
+
+// CS4: Unused Imports
+import { unusedHelper, anotherUnused } from './utils';
+import * as everythingUnused from './everything';
+
+// CS4: Unused Variables
+function processItemsViolation(items: Item[]) {
+  const unusedConfig = loadConfig();
+  const unusedHelper = createHelper();
+
+  return items.map((item) => item.name);
+}
+
+// CS4: Commented-Out Code
+function handleRequestViolation(req: Request) {
+  // const oldWay = processOldWay(req);
+  // if (oldWay.success) {
+  //   return oldWay.result;
+  // }
+
+  // TODO: Remove old code after migration
+  // const legacyResult = legacyHandler(req);
+  // legacyResult.transformed = true;
+  // return legacyResult;
+
+  return processNewWay(req);
+}
+
+// CS4: Dead Code
+function processWithDeadCode(value: number): number {
+  if (value > 0) {
+    return value * 2;
+  }
+
+  return value;
+
+  // Dead code - unreachable
+  console.log('This never executes');
+  return value * 3;
+}
+
+// Missing Documentation on Public API
+export function calculateComplexMetric(
+  data: MetricData[],
+  weights: number[],
+  normalize: boolean,
+  threshold: number
+): ComplexResult {
+  // No documentation for public function with many parameters
+  // Users have to read the code to understand behavior
+  return internalCalculation(data, weights, normalize, threshold);
+}
+
+// Outdated Documentation
+/**
+ * Processes user data
+ * @param user - The user to process
+ * @deprecated Use newProcessUser instead
+ */
+function processUserViolation(user: User, options: ProcessOptions): Result {
+  // Function signature changed but docs not updated
+  // 'options' parameter not documented
+  // Not actually deprecated
+  return doProcessing(user, options);
+}
+
+// Inconsistent Error Handling
+async function fetchAllViolation() {
+  // Mix of error handling styles in same function
+  const users = await fetch('/users').catch(() => []);
+
+  let orders;
+  try {
+    orders = await fetch('/orders');
+  } catch (e) {
+    orders = [];
+  }
+
+  const products = await fetch('/products'); // No error handling
+
+  return { users, orders, products };
+}
+
+// Inconsistent Async Style
+async function loadDataViolation() {
+  // Mix of .then() and await in same function
+  const config = await loadConfig();
+
+  return fetch(config.url)
+    .then((res) => res.json())
+    .then((data) => {
+      return processData(data);
+    });
+}

package/skills/code-review/examples/anti-patterns/type-safety.ts

@@ -0,0 +1,108 @@
+/**
+ * Type Safety Anti-Patterns
+ *
+ * DO NOT use these patterns in production code.
+ * Each example demonstrates a type safety hole.
+ */
+
+// Explicit `any` - bypasses type checking entirely
+function processDataUnsafe(data: any) {
+  // No type checking, any access is allowed
+  return data.deeply.nested.property.that.might.not.exist;
+}
+
+// Return type `any` - loses type information for callers
+async function fetchUserUnsafe(id: string): Promise<any> {
+  const response = await fetch(`/api/users/${id}`);
+  return response.json();
+}
+
+// Variable typed as `any`
+const configUnsafe: any = JSON.parse(rawConfig);
+console.log(configUnsafe.setting.that.might.not.exist);
+
+// Implicit `any` from missing parameter type (with noImplicitAny: false)
+function calculateUnsafe(a, b) {
+  return a + b; // Could be string concatenation or number addition
+}
+
+// Non-null assertion abuse
+interface User {
+  name: string;
+  profile?: {
+    avatar?: string;
+  };
+}
+
+function getAvatarUnsafe(user: User | null): string {
+  // BAD: Assumes user and profile exist
+  return user!.profile!.avatar!;
+}
+
+// Optional chaining gap - mixed `.` and `?.`
+function getNameUnsafe(user: User | null): string {
+  // BAD: `profile` could be undefined, but we use `.avatar`
+  return user?.profile.avatar ?? 'default';
+}
+
+// Truthy check when 0 or "" is valid
+function getCountUnsafe(items?: number): number {
+  // BAD: Returns 10 when items is 0
+  if (!items) {
+    return 10;
+  }
+  return items;
+}
+
+// Double assertion - almost always wrong
+function convertUnsafe(value: string): number {
+  // BAD: Forces incompatible type conversion
+  return value as unknown as number;
+}
+
+// Type assertion without validation
+interface Config {
+  apiUrl: string;
+  timeout: number;
+}
+
+function loadConfigUnsafe(): Config {
+  const raw = JSON.parse(process.env.CONFIG!);
+  // BAD: No validation that raw matches Config shape
+  return raw as Config;
+}
+
+// Widening to `any` then narrowing
+function parseResponseUnsafe(response: Response): UserData {
+  const data = response.json() as any;
+  // BAD: Loses all type safety
+  return data as UserData;
+}
+
+// Type assertion on non-overlapping types (via unknown)
+function stringToNumberUnsafe(str: string): number {
+  // This compiles but is nonsensical
+  return str as unknown as number;
+}
+
+// Ignoring null/undefined with assertion
+async function getFirstUserUnsafe(): Promise<User> {
+  const users = await fetchUsers();
+  // BAD: Array could be empty
+  return users[0]!;
+}
+
+// Untyped catch clause
+async function fetchDataUnsafe() {
+  try {
+    return await fetch('/api/data');
+  } catch (e) {
+    // BAD: `e` is `unknown` but used as Error
+    console.log(e.message); // TypeScript error in strict mode
+  }
+}
+
+// Generic constraint `any` - defeats purpose of generics
+function wrapUnsafe<T extends any>(value: T): { wrapped: T } {
+  return { wrapped: value };
+}

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

@@ -0,0 +1,195 @@
+/**
+ * Linting Recommended Patterns
+ *
+ * These examples demonstrate clean code practices.
+ */
+
+// Early returns instead of deep nesting
+function processOrderSafe(order: Order | null) {
+  if (!order) return;
+  if (!order.items?.length) return;
+
+  for (const item of order.items) {
+    if (item.quantity <= 0) continue;
+    if (item.price <= 0) continue;
+
+    console.log(item);
+  }
+}
+
+// Small, focused functions
+async function handleCheckoutSafe(cart: Cart, user: User): Promise<Order> {
+  validateCart(cart);
+
+  const totals = calculateTotals(cart, user);
+  const order = createOrder(cart, user, totals);
+
+  await saveOrder(order, cart);
+  await sendNotifications(order, user);
+  await updateUserStats(user, totals.total);
+
+  return order;
+}
+
+function validateCart(cart: Cart): void {
+  if (!cart.items.length) throw new Error('Empty cart');
+
+  for (const item of cart.items) {
+    if (!item.available) throw new Error('Item unavailable');
+    if (item.quantity > item.stock) throw new Error('Insufficient stock');
+  }
+}
+
+interface Totals {
+  subtotal: number;
+  discount: number;
+  tax: number;
+  shipping: number;
+  total: number;
+}
+
+function calculateTotals(cart: Cart, user: User): Totals {
+  const subtotal = cart.items.reduce(
+    (sum, item) => sum + item.price * item.quantity,
+    0
+  );
+  const discount = user.isPremium ? subtotal * 0.1 : 0;
+  const tax = (subtotal - discount) * 0.08;
+  const shipping = subtotal > 100 ? 0 : 10;
+  const total = subtotal - discount + tax + shipping;
+
+  return { subtotal, discount, tax, shipping, total };
+}
+
+// Descriptive naming
+function transformProductData(rawProducts: RawProduct[]): TransformedProduct[] {
+  return rawProducts.map((product) => {
+    const discountedPrice = product.basePrice * 2;
+    return { ...product, discountedPrice };
+  });
+}
+
+// Meaningful variable names
+function calculateRectangleArea(
+  width: number,
+  height: number,
+  margin: number,
+  padding: number
+): number {
+  const innerWidth = width - margin * 2;
+  const innerHeight = height - padding * 2;
+  const area = innerWidth * innerHeight;
+  return area;
+}
+
+// Accurate naming
+const currentUser = getUser(); // Singular, clear
+const validationResult = validate(data); // Describes what it returns
+const permanentDiscountRate = 0.15; // Accurate description
+
+// Single responsibility functions
+function parseInput(input: string): ParsedData {
+  return JSON.parse(input);
+}
+
+function validateData(data: ParsedData): void {
+  if (!data.name) throw new Error('Missing name');
+}
+
+function transformData(data: ParsedData): TransformedData {
+  return { ...data, name: data.name.toUpperCase() };
+}
+
+function saveData(data: TransformedData): void {
+  localStorage.setItem('data', JSON.stringify(data));
+}
+
+function notifyDataUpdate(data: TransformedData): void {
+  dispatchEvent(new CustomEvent('dataUpdated', { detail: data }));
+}
+
+function processInput(input: string): TransformedData {
+  const parsed = parseInput(input);
+  validateData(parsed);
+  const transformed = transformData(parsed);
+  saveData(transformed);
+  notifyDataUpdate(transformed);
+  return transformed;
+}
+
+// Named conditions for complex logic
+function canAccessResource(user: User, resource: Resource): boolean {
+  const isAdmin = user.role === 'admin';
+  const isManagerOfDepartment =
+    user.role === 'manager' && user.department === resource.department;
+  const isEmployeeWithPublicAccess =
+    user.role === 'employee' &&
+    user.department === resource.department &&
+    resource.accessLevel === 'public';
+  const hasDirectPermission = user.permissions.includes(resource.id);
+  const hasSharedAccess =
+    resource.sharedWith.includes(user.id) && !resource.revoked;
+
+  return (
+    isAdmin ||
+    isManagerOfDepartment ||
+    isEmployeeWithPublicAccess ||
+    hasDirectPermission ||
+    hasSharedAccess
+  );
+}
+
+// Extract shared logic to avoid duplication
+function validateEmail(email: string): void {
+  if (!email) throw new Error('Email required');
+  if (!email.includes('@')) throw new Error('Invalid email');
+  if (email.length > 255) throw new Error('Email too long');
+}
+
+function createUserSafe(data: UserData) {
+  validateEmail(data.email);
+  // ...create user
+}
+
+function updateUserSafe(id: string, data: UserData) {
+  validateEmail(data.email);
+  // ...update user
+}
+
+// Consistent async style
+async function fetchDataConsistent() {
+  const response = await fetch('/api/data');
+  const data = await response.json();
+  return processData(data);
+}
+
+async function fetchOtherDataConsistent() {
+  const response = await fetch('/api/other');
+  const data = await response.json();
+  return processData(data);
+}
+
+// Named constants instead of magic numbers
+const SHIPPING_RATES = {
+  LIGHT_PER_MILE: 0.5,
+  LIGHT_BASE: 3.99,
+  MEDIUM_PER_MILE: 0.75,
+  MEDIUM_BASE: 7.99,
+  HEAVY_PER_MILE: 1.25,
+  HEAVY_BASE: 14.99,
+} as const;
+
+const WEIGHT_THRESHOLDS = {
+  LIGHT: 5,
+  MEDIUM: 20,
+} as const;
+
+function calculateShippingSafe(weight: number, distance: number): number {
+  if (weight < WEIGHT_THRESHOLDS.LIGHT) {
+    return distance * SHIPPING_RATES.LIGHT_PER_MILE + SHIPPING_RATES.LIGHT_BASE;
+  }
+  if (weight < WEIGHT_THRESHOLDS.MEDIUM) {
+    return distance * SHIPPING_RATES.MEDIUM_PER_MILE + SHIPPING_RATES.MEDIUM_BASE;
+  }
+  return distance * SHIPPING_RATES.HEAVY_PER_MILE + SHIPPING_RATES.HEAVY_BASE;
+}

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

@@ -0,0 +1,154 @@
+/**
+ * Security Recommended Patterns
+ *
+ * These examples demonstrate secure coding practices.
+ */
+
+// A03:2021 - SQL Injection Prevention
+// GOOD: Parameterized query
+async function getUserByIdSafe(userId: string) {
+  const query = 'SELECT * FROM users WHERE id = ?';
+  return db.query(query, [userId]);
+}
+
+// A03:2021 - Command Injection Prevention
+// GOOD: Use array-based spawn, validate input
+function processFileSafe(filename: string) {
+  const { spawnSync } = require('child_process');
+
+  // Validate filename contains only safe characters
+  if (!/^[\w.-]+$/.test(filename)) {
+    throw new Error('Invalid filename');
+  }
+
+  // Use array form to prevent shell interpretation
+  spawnSync('grep', ['pattern', filename]);
+}
+
+// A03:2021 - XSS Prevention
+// GOOD: Use textContent or proper escaping
+function renderCommentSafe(comment: string) {
+  const element = document.getElementById('comments');
+  element.textContent = comment; // Safe: treated as text, not HTML
+}
+
+// Alternative: Use a sanitization library
+function renderCommentWithSanitization(comment: string) {
+  const DOMPurify = require('dompurify');
+  const clean = DOMPurify.sanitize(comment);
+  document.getElementById('comments').innerHTML = clean;
+}
+
+// A02:2021 - Secrets Management
+// GOOD: Use environment variables
+const API_KEY = process.env.API_KEY;
+const DB_PASSWORD = process.env.DB_PASSWORD;
+
+// Validate secrets are present at startup
+if (!API_KEY || !DB_PASSWORD) {
+  throw new Error('Required environment variables not set');
+}
+
+// A02:2021 - Strong Cryptography
+// GOOD: bcrypt for password hashing
+import * as bcrypt from 'bcrypt';
+
+async function hashPasswordSafe(password: string): Promise<string> {
+  const saltRounds = 12;
+  return bcrypt.hash(password, saltRounds);
+}
+
+async function verifyPassword(password: string, hash: string): Promise<boolean> {
+  return bcrypt.compare(password, hash);
+}
+
+// A02:2021 - Secure Random
+// GOOD: crypto.randomBytes for security-sensitive operations
+import * as crypto from 'crypto';
+
+function generateTokenSafe(): string {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+// A01:2021 - Authorization Check
+// GOOD: Verify ownership before returning data
+async function getDocumentSafe(documentId: string, userId: string) {
+  const document = await db.documents.findById(documentId);
+
+  if (!document) {
+    throw new NotFoundError('Document not found');
+  }
+
+  if (document.ownerId !== userId) {
+    throw new ForbiddenError('Access denied');
+  }
+
+  return document;
+}
+
+// A01:2021 - Path Traversal Prevention
+// GOOD: Validate and normalize path
+import * as path from 'path';
+
+function readFileSafe(userPath: string) {
+  const uploadsDir = path.resolve('./uploads');
+  const requestedPath = path.resolve(uploadsDir, userPath);
+
+  // Ensure path is within uploads directory
+  if (!requestedPath.startsWith(uploadsDir)) {
+    throw new Error('Invalid path');
+  }
+
+  const fs = require('fs');
+  return fs.readFileSync(requestedPath);
+}
+
+// A07:2021 - Session Regeneration
+// GOOD: Regenerate session after authentication
+async function loginSafe(req: Request, res: Response) {
+  const user = await authenticate(req.body);
+
+  // Regenerate session to prevent fixation
+  req.session.regenerate((err) => {
+    if (err) throw err;
+    req.session.userId = user.id;
+    res.json({ success: true });
+  });
+}
+
+// A09:2021 - Safe Logging
+// GOOD: Never log sensitive data
+function authenticateSafe(username: string, password: string) {
+  console.log(`Login attempt for user: ${username}`);
+  // Password is NOT logged
+  const result = verifyCredentials(username, password);
+  console.log(`Login result for ${username}: ${result ? 'success' : 'failure'}`);
+}
+
+// A10:2021 - SSRF Prevention
+// GOOD: Allowlist for external URLs
+const ALLOWED_HOSTS = ['api.example.com', 'cdn.example.com'];
+
+async function fetchUrlSafe(url: string) {
+  const parsedUrl = new URL(url);
+
+  if (!ALLOWED_HOSTS.includes(parsedUrl.hostname)) {
+    throw new Error('URL not in allowlist');
+  }
+
+  const response = await fetch(url);
+  return response.text();
+}
+
+// A05:2021 - Production Error Handling
+// GOOD: Generic error message, log details server-side
+function handleErrorSafe(error: Error, res: Response) {
+  // Log full details server-side
+  console.error('Internal error:', error);
+
+  // Return generic message to client
+  res.status(500).json({
+    error: 'An internal error occurred',
+    requestId: generateRequestId(), // For support correlation
+  });
+}