@qball-inc/the-bulwark 1.0.0

package/skills/code-review/references/standards-patterns.md

@@ -0,0 +1,246 @@
+# Coding Standards Patterns Reference
+
+Patterns for the Coding Standards section of code-review skill.
+
+---
+
+## Atomic Principles (from Rules.md)
+
+### CS1: Single Responsibility
+
+Every function, class, and module should have ONE purpose.
+
+| Pattern | Detection | Severity |
+|---------|-----------|----------|
+| Function does multiple things | Multiple comments describing phases | Important |
+| Class with unrelated methods | Methods operating on different data | Important |
+| Module with mixed exports | Utilities + domain logic in same file | Suggestion |
+
+**Good Example:**
+```typescript
+// Single purpose: validate email format
+function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+```
+
+**Anti-pattern:**
+```typescript
+// Multiple purposes: validate AND send AND log
+function processEmail(email: string): void {
+  if (!isValidEmail(email)) throw new Error('Invalid');
+  sendEmail(email);
+  logAction('email_sent', email);
+}
+```
+
+### CS2: No Magic
+
+No implicit behaviors, hidden dependencies, or undocumented side effects.
+
+| Pattern | Detection | Severity |
+|---------|-----------|----------|
+| Magic numbers | Hardcoded values without names | Suggestion |
+| Hidden mutations | Function modifies input object | Important |
+| Implicit globals | Using undeclared global state | Important |
+| Side effects in getters | Property access triggers actions | Important |
+
+**Good Example:**
+```typescript
+const MAX_RETRY_ATTEMPTS = 3;
+const TIMEOUT_MS = 5000;
+
+async function fetchWithRetry(url: string): Promise<Response> {
+  // explicit constants, no hidden behavior
+}
+```
+
+**Anti-pattern:**
+```typescript
+async function fetch(url: string): Promise<Response> {
+  // Magic numbers, unclear behavior
+  for (let i = 0; i < 3; i++) {
+    await sleep(5000);
+  }
+}
+```
+
+### CS3: Fail Fast
+
+Validate inputs at boundaries, return errors early, no silent failures.
+
+| Pattern | Detection | Severity |
+|---------|-----------|----------|
+| Missing input validation | Public function without checks | Important |
+| Silent catch | `catch (e) {}` with no handling | Important |
+| Default on error | Returning default instead of throwing | Suggestion |
+| Deep error propagation | Error handled far from source | Suggestion |
+
+**Good Example:**
+```typescript
+function divide(a: number, b: number): number {
+  if (b === 0) throw new Error('Division by zero');
+  return a / b;
+}
+```
+
+**Anti-pattern:**
+```typescript
+function divide(a: number, b: number): number {
+  try {
+    return a / b;
+  } catch {
+    return 0; // Silent failure, incorrect result
+  }
+}
+```
+
+### CS4: Clean Code
+
+No unused code, no commented-out blocks, complete deletions.
+
+| Pattern | Detection | Severity |
+|---------|-----------|----------|
+| Unused imports | Import not referenced in file | Suggestion |
+| Unused variables | Variable declared but never used | Suggestion |
+| Commented-out code | Large blocks of commented code | Important |
+| Dead code | Unreachable code paths | Important |
+
+**Detection Note:** Most of these are caught by linters. This section verifies linter was run.
+
+---
+
+## Documentation Patterns
+
+### When to Document
+
+| Situation | Documentation Required |
+|-----------|----------------------|
+| Public API | Yes - JSDoc with @param, @returns |
+| Complex algorithm | Yes - Explain approach, not code |
+| Non-obvious decision | Yes - Why this approach |
+| Simple getter/setter | No - Self-evident |
+| Internal helper | Optional |
+
+### Good Documentation
+
+```typescript
+/**
+ * Calculate compound interest with monthly compounding.
+ *
+ * Uses the formula: A = P(1 + r/n)^(nt)
+ *
+ * @param principal - Initial investment amount
+ * @param rate - Annual interest rate (0.05 = 5%)
+ * @param years - Investment duration in years
+ * @returns Final amount after compound interest
+ */
+function calculateCompoundInterest(
+  principal: number,
+  rate: number,
+  years: number
+): number {
+  const n = 12; // Monthly compounding
+  return principal * Math.pow(1 + rate / n, n * years);
+}
+```
+
+### Anti-pattern Documentation
+
+```typescript
+// BAD: Describes what, not why
+// This function adds two numbers
+function add(a: number, b: number): number {
+  return a + b;
+}
+
+// BAD: Outdated documentation
+/**
+ * @deprecated Use newFunction instead
+ * @param items - List of items to process
+ */
+function process(items: Item[], config: Config): Result {
+  // Config parameter not documented
+}
+```
+
+---
+
+## Pattern Adherence
+
+### Project-Specific Patterns
+
+Check for consistency with existing codebase patterns:
+
+| Pattern Type | Check |
+|--------------|-------|
+| Error handling | Same error types used? |
+| Async patterns | Consistent Promise vs async/await? |
+| Naming conventions | Follows existing style? |
+| File organization | Matches project structure? |
+
+### Common Inconsistencies
+
+| Pattern | Example | Fix |
+|---------|---------|-----|
+| Mixed async styles | `then()` and `await` in same file | Pick one |
+| Inconsistent exports | Named vs default exports | Follow project standard |
+| Mixed error types | Custom errors vs plain Error | Use project error classes |
+
+---
+
+## Architecture Patterns
+
+### Layer Violations
+
+| Violation | Example | Severity |
+|-----------|---------|----------|
+| UI → Database | Component directly querying DB | Important |
+| Controller → Repository | Skipping service layer | Suggestion |
+| Cross-feature import | Feature A importing Feature B internals | Important |
+
+### Dependency Direction
+
+```
+┌─────────────────────────────────────────┐
+│              Presentation               │
+│         (components, pages)             │
+└───────────────────┬─────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│              Application                │
+│      (services, use cases)              │
+└───────────────────┬─────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│               Domain                    │
+│       (entities, value objects)         │
+└───────────────────┬─────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│            Infrastructure               │
+│     (repositories, external APIs)       │
+└─────────────────────────────────────────┘
+
+Arrows indicate allowed import direction.
+```
+
+---
+
+## Detection Priority
+
+1. **Fail fast violations**: Check public function entry points
+2. **Single responsibility**: Look for "and" in function names/descriptions
+3. **Magic values**: Scan for hardcoded numbers, strings
+4. **Documentation gaps**: Check public exports
+
+---
+
+## False Positive Prevention
+
+**Skip these patterns:**
+- Prototype/experimental code with explicit markers
+- Third-party integration matching external conventions
+- Auto-generated code (migrations, GraphQL schemas)
+- Configuration files with intentional magic values
+- Test files with intentional violations for testing

package/skills/code-review/references/type-safety-patterns.md

@@ -0,0 +1,130 @@
+# Type Safety Patterns Reference
+
+Patterns for the Type Safety section of code-review skill.
+
+---
+
+## `any` Usage Patterns
+
+### Explicit `any`
+
+| Pattern | Detection | Severity | Example |
+|---------|-----------|----------|---------|
+| Parameter typed as `any` | `: any` in function signature | Important | `function process(data: any)` |
+| Return typed as `any` | `: any` as return type | Important | `function fetch(): any` |
+| Variable typed as `any` | `const x: any =` | Important | `const response: any = await fetch()` |
+| Generic constraint `any` | `<T extends any>` | Important | Usually unnecessary |
+
+**When `any` is Acceptable:**
+- JSON parsing with immediate schema validation
+- Third-party library interop with no types
+- Type assertions for testing flexibility
+- Gradual migration from JavaScript
+
+### Implicit `any`
+
+| Pattern | Detection | Severity | Example |
+|---------|-----------|----------|---------|
+| Missing parameter type | No type annotation, no inference | Important | `function process(data)` |
+| Missing return type | Complex function without explicit return | Suggestion | `function calculate() { ... }` |
+| Untyped catch clause | `catch (e)` without type annotation | Suggestion | `catch (error) { console.log(error.message) }` |
+
+**tsconfig Recommendation:**
+```json
+{
+  "compilerOptions": {
+    "noImplicitAny": true,
+    "strictNullChecks": true
+  }
+}
+```
+
+---
+
+## Null/Undefined Handling
+
+### Unsafe Patterns
+
+| Pattern | Detection | Severity | Example |
+|---------|-----------|----------|---------|
+| Non-null assertion abuse | `!` on potentially null values | Important | `user!.name` when user may be null |
+| Optional chaining gap | Mixed `?.` and `.` on same chain | Important | `user?.profile.name` (profile may be undefined) |
+| Truthy check inadequate | `if (value)` when 0 or "" is valid | Important | `if (count)` when 0 is valid |
+| Missing nullish handling | No `?? defaultValue` for optional | Suggestion | `return config.timeout` without fallback |
+
+### Safe Patterns
+
+| Pattern | Example |
+|---------|---------|
+| Explicit null check | `if (user !== null && user !== undefined)` |
+| Optional chaining throughout | `user?.profile?.name` |
+| Nullish coalescing | `config.timeout ?? 30000` |
+| Type narrowing | `if ('name' in user)` |
+
+---
+
+## Unsafe Type Assertions
+
+### High-Risk Patterns
+
+| Pattern | Detection | Severity | Example |
+|---------|-----------|----------|---------|
+| Double assertion | `as unknown as T` | Critical | `value as unknown as SpecificType` |
+| Widening then narrowing | Cast to `any` then to specific | Critical | `(value as any) as ExpectedType` |
+| Non-overlapping assertion | Types share no properties | Important | `string as number` |
+| Assertion without validation | Cast external data without checks | Important | `JSON.parse(input) as Config` |
+
+### Safe Assertion Patterns
+
+| Pattern | Example |
+|---------|---------|
+| Type guard before assertion | `if (isConfig(data)) { return data as Config }` |
+| Schema validation | `const config = configSchema.parse(input)` |
+| Branded types | `type UserId = string & { readonly brand: unique symbol }` |
+
+---
+
+## Common Bypasses
+
+### Library Interop
+
+```typescript
+// SUSPECTED: Library returns any
+import { externalLib } from 'untyped-lib';
+const result = externalLib.process(data); // any
+
+// RECOMMENDED: Wrap with type
+interface ProcessResult { status: string; data: unknown }
+const result: ProcessResult = externalLib.process(data);
+```
+
+### JSON Parsing
+
+```typescript
+// SUSPECTED: Unvalidated JSON
+const config = JSON.parse(rawConfig); // any
+
+// RECOMMENDED: Validate immediately
+const config = JSON.parse(rawConfig);
+if (!isValidConfig(config)) throw new Error('Invalid config');
+```
+
+---
+
+## Detection Priority
+
+1. **Explicit `any` annotations**: Direct code search
+2. **Type assertions**: Look for `as` keyword
+3. **Non-null assertions**: Look for `!` not in conditionals
+4. **Implicit any**: Requires type checking context (tsconfig)
+
+---
+
+## False Positive Prevention
+
+**Skip these patterns:**
+- `any` in test files for mock flexibility
+- `any` with immediate `typeof` or `instanceof` check
+- Type assertions in type definition files (.d.ts)
+- `unknown` usage (proper unknown handling is safe)
+- Assertion in return position with JSDoc validation note

package/skills/component-patterns/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: component-patterns
+description: Per-component-type verification approaches. Use when generating verification scripts for different component types.
+user-invocable: false
+---
+
+# Component Patterns
+
+## Purpose
+
+Provide verification strategies for different component types. This skill defines how to
+test real behavior for CLIs, servers, parsers, processes, databases, and external APIs.
+
+## When to Use
+
+Load this skill when:
+- Generating verification scripts via bulwark-verify skill
+- Determining how to test a specific component type
+- Implementing test-audit Step 7 rewrites
+
+---
+
+## Component Type Detection
+
+Analyze the code to determine component type based on these indicators:
+
+| Indicators | Component Type | Pattern Reference |
+|------------|----------------|-------------------|
+| Imports `child_process`, has `spawn`/`exec`/`execSync` | Process Spawner | `references/pattern-process-spawner.md` |
+| Imports `http`/`https`/`express`/`fastify`/`koa`, has `listen()` | HTTP Server | `references/pattern-http-server.md` |
+| Imports `fs`, reads/parses files, has parse functions | File Parser | `references/pattern-file-parser.md` |
+| Has CLI argument parsing (`process.argv`, `yargs`, `commander`, `argparse`) | CLI Command | `references/pattern-cli-command.md` |
+| Imports database driver (`pg`, `mysql`, `mongoose`, `sqlite`, `prisma`) | Database | `references/pattern-database.md` |
+| Makes outbound HTTP calls (`fetch`, `axios`, `got`, `requests`) | External API | `references/pattern-external-api.md` |
+
+---
+
+## Pattern Reference Files
+
+Each pattern reference contains:
+- **Strategy**: High-level approach for testing the component type
+- **Templates**: Ready-to-use verification script templates in Bash, Node/Jest, and Python/pytest
+- **Placeholders**: Variables to substitute with component-specific values
+
+### Available Patterns
+
+| Pattern | File | Languages |
+|---------|------|-----------|
+| CLI Command | `references/pattern-cli-command.md` | Bash, Node, Python |
+| HTTP Server | `references/pattern-http-server.md` | Bash, Node (supertest), Python |
+| File Parser | `references/pattern-file-parser.md` | Bash, Node, Python |
+| Process Spawner | `references/pattern-process-spawner.md` | Bash, Node |
+| Database | `references/pattern-database.md` | Node, Python, Bash (SQLite) |
+| External API | `references/pattern-external-api.md` | Node (MSW), Python (responses) |
+
+---
+
+## Usage Instructions
+
+### Step 1: Detect Component Type
+
+Analyze the target component code using the detection table above.
+
+### Step 2: Load Pattern Reference
+
+Read the appropriate pattern file from `references/`:
+
+```
+Read skills/component-patterns/references/pattern-{type}.md
+```
+
+### Step 3: Select Template
+
+Choose the template that matches the project language:
+- **Node projects** (`package.json` present): Use Node/Jest template
+- **Python projects** (`pyproject.toml` or `setup.py` present): Use Python/pytest template
+- **Generic/Other**: Use Bash template
+
+### Step 4: Substitute Placeholders
+
+Replace all `{placeholder}` values with component-specific information:
+
+| Common Placeholders | Description |
+|---------------------|-------------|
+| `{component_name}` | Name of the component being tested |
+| `{component_path}` | Import path to the module |
+| `{port}` | Network port (for servers/processes) |
+| `{expected_value}` | Expected output to verify |
+
+---
+
+## Quick Reference: Component to Pattern
+
+| Component Type | Verification Strategy | Key Assertion |
+|----------------|----------------------|---------------|
+| CLI Command | Spawn, capture stdout/stderr | Exit code + output text |
+| HTTP Server | Start, HTTP request, verify response | Status code + response body |
+| File Parser | Create input, parse, check structure | Parsed fields + values |
+| Process Spawner | Spawn, check port/pid, verify behavior | Process alive + responds |
+| Database | Setup DB, execute ops, query state | Records exist/modified |
+| External API | MSW intercept, real fetch, check result | Response data matches |
+
+---
+
+## Key Principle: Real Verification
+
+All patterns follow the same principle: **verify observable output, not mock calls**.
+
+| Anti-Pattern | Real Pattern |
+|--------------|--------------|
+| `expect(spawn).toHaveBeenCalled()` | `expect(await checkPort(8080)).toBe(true)` |
+| `expect(fs.writeFile).toHaveBeenCalled()` | `expect(fs.existsSync(path)).toBe(true)` |
+| `expect(fetch).toHaveBeenCalledWith(url)` | `const resp = await fetch(url); expect(resp.status).toBe(200)` |
+| `expect(db.save).toHaveBeenCalled()` | `const found = await db.find(id); expect(found).toBeDefined()` |
+
+---
+
+## Diagnostic Output
+
+Write diagnostic output to `logs/diagnostics/component-patterns-{YYYYMMDD-HHMMSS}.yaml`:
+
+```yaml
+skill: component-patterns
+timestamp: {ISO-8601}
+diagnostics:
+  component_type_detected: cli|http|file-parser|process|database|api
+  pattern_applied: "CLI Command Verification"
+  template_language: bash|node|python
+  files_analyzed: 1
+  completion_status: success
+```

package/skills/component-patterns/references/pattern-cli-command.md

@@ -0,0 +1,118 @@
+# Pattern 1: CLI Command Verification
+
+## Strategy
+
+Spawn the CLI as a child process, capture stdout/stderr, verify exit code and output.
+
+---
+
+## Template (Bash)
+
+```bash
+#!/bin/bash
+# CLI Verification: {component_name}
+set -e
+
+echo "=== CLI Verification: {component_name} ==="
+
+# Test 1: Basic invocation
+echo -n "Test 1: Basic invocation... "
+OUTPUT=$({cli_command} {args} 2>&1)
+EXIT_CODE=$?
+if [ $EXIT_CODE -eq 0 ]; then
+  echo "PASS (exit code 0)"
+else
+  echo "FAIL (exit code $EXIT_CODE)"
+  exit 1
+fi
+
+# Test 2: Output contains expected text
+echo -n "Test 2: Output validation... "
+if echo "$OUTPUT" | grep -q "{expected_text}"; then
+  echo "PASS (found expected text)"
+else
+  echo "FAIL (missing expected text)"
+  echo "Output was: $OUTPUT"
+  exit 1
+fi
+
+# Test 3: Error handling
+echo -n "Test 3: Error handling... "
+ERROR_OUTPUT=$({cli_command} --invalid-flag 2>&1) || true
+if echo "$ERROR_OUTPUT" | grep -qi "error\|usage\|invalid"; then
+  echo "PASS (error message shown)"
+else
+  echo "FAIL (no error message)"
+  exit 1
+fi
+
+echo "=== All tests passed ==="
+```
+
+---
+
+## Template (Node/Jest)
+
+```javascript
+const { execSync, spawn } = require('child_process');
+
+describe('{component_name} CLI', () => {
+  test('basic invocation succeeds', () => {
+    const output = execSync('{cli_command} {args}', { encoding: 'utf8' });
+    expect(output).toContain('{expected_text}');
+  });
+
+  test('returns correct exit code on success', (done) => {
+    const result = spawn('{cli_command}', ['{args}']);
+    result.on('close', (code) => {
+      expect(code).toBe(0);
+      done();
+    });
+  });
+
+  test('shows error on invalid input', () => {
+    expect(() => {
+      execSync('{cli_command} --invalid', { encoding: 'utf8', stdio: 'pipe' });
+    }).toThrow();
+  });
+});
+```
+
+---
+
+## Template (Python/pytest)
+
+```python
+import subprocess
+import pytest
+
+class TestCLI:
+    def test_basic_invocation(self):
+        result = subprocess.run(
+            ['{cli_command}', '{args}'],
+            capture_output=True,
+            text=True
+        )
+        assert result.returncode == 0
+        assert '{expected_text}' in result.stdout
+
+    def test_error_handling(self):
+        result = subprocess.run(
+            ['{cli_command}', '--invalid-flag'],
+            capture_output=True,
+            text=True
+        )
+        assert result.returncode != 0
+        assert 'error' in result.stderr.lower() or 'usage' in result.stderr.lower()
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{component_name}` | Name of the CLI component being tested |
+| `{cli_command}` | The CLI command to execute |
+| `{args}` | Command arguments |
+| `{expected_text}` | Text expected in output |