ashaykubal/component-patterns

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:

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