code-quality

Original source / Raw SKILL.md

---
name: code-quality
description: >
  Code quality verification for Schmock. Run tests, check coverage, validate
  compliance. Use when testing, reviewing code, or preparing for commits.
argument-hint: "test all|unit|bdd|<package> | validate | coverage <package>"
allowed-tools:
  - Bash(bash .claude/skills/code-quality/scripts/test.sh *)
  - Bash(bash .claude/skills/code-quality/scripts/validate.sh)
  - Bash(bash .claude/skills/code-quality/scripts/coverage.sh *)
---

# Schmock Code Quality Skill

## The Gate: `/code-quality validate`

The primary command. Runs all 6 quality stages in order and reports pass/fail with fix hints:

| # | Stage | What it checks | Auto-fix? |
|---|-------|---------------|-----------|
| 1 | **Lint** | Biome: formatting, imports, code smells | `bun lint:fix` |
| 2 | **Typecheck** | tsc --build per package | Manual |
| 3 | **Knip** | Dead exports, unused dependencies | Manual |
| 4 | **ESLint** | `as` type assertions (zero tolerance) | Manual |
| 5 | **Unit** | `packages/*/src/**/*.test.ts` | Manual |
| 6 | **BDD** | `packages/*/src/steps/*.steps.ts` vs `features/*.feature` | Manual |

All 6 must pass before committing. The pre-commit hook enforces Lint + Typecheck + Unit + BDD automatically.

### When a stage fails

| Failed stage | What to do |
|-------------|------------|
| **Lint** | Run `bun lint:fix` — most issues auto-fix. For remaining: check biome output for the rule name and fix manually. |
| **Typecheck** | Run `bun typecheck` for full errors. Usually a missing import, wrong return type, or ambient type mismatch in `packages/core/schmock.d.ts`. |
| **Knip** | Run `bun knip` to see unused exports/deps. Either delete the dead code or, if intentional, add to `knip.json` ignore. |
| **ESLint** | Run `bun eslint` to see `as` casts. Replace with: `toHttpMethod()` for HttpMethod, `errorMessage()` for unknown errors, `"prop" in obj` narrowing, `FakerSchema` interface for jsf extensions. Never add `as` — use `satisfies` if needed. |
| **Unit** | Run `bun test:unit` for full output. Read the failing assertion, fix the source or update the test expectation. |
| **BDD** | Run `bun test:bdd` for full output. Common issues: step text doesn't match `.feature` file exactly, or a new Scenario is missing step definitions. Each step text must be unique within a Scenario. |

### Zero `as` policy

The codebase has zero unsafe type assertions. Patterns to avoid `as`:

| Instead of | Use |
|-----------|-----|
| `method as HttpMethod` | `toHttpMethod(method)` — runtime validation |
| `(error as Error).message` | `errorMessage(error)` helper or `instanceof Error` guard |
| `(obj as any).faker` | `FakerSchema` interface extending JSONSchema7, or `"faker" in obj` guard |
| `body as Record<string, unknown>` | `"code" in body && body.code === ...` narrowing |
| `error as SchmockError` | Redundant after `instanceof SchmockError` — just use `error.code` |
| `value as SomeType` | `satisfies SomeType` (checks without asserting) |

### Code smell detection stack

| Tool | Rules | Config |
|------|-------|--------|
| **Biome** | `noNonNullAssertion`, `noShadow`, `noEvolvingTypes`, `noFloatingPromises`, `noMisusedPromises`, `noImportCycles` | `biome.json` |
| **Knip** | Dead exports, unused dependencies, unlisted deps | `knip.json` |
| **typescript-eslint** | `no-unsafe-type-assertion` (error) | `eslint.config.js` |

## Testing

### Commands

| Command | Description |
|---------|-------------|
| `/code-quality validate` | **Full gate** — Lint, Typecheck, Knip, ESLint, Unit, BDD |
| `/code-quality test all` | Typecheck + Unit + BDD (no lint/knip/eslint) |
| `/code-quality test unit` | Unit tests only |
| `/code-quality test bdd` | BDD tests only |
| `/code-quality test <pkg>` | Tests for one package: core, schema, express, angular, validation, query |
| `/code-quality coverage <pkg>` | Per-package coverage report |

### Test types

| Type | Location | Config | Purpose |
|------|----------|--------|---------|
| Unit (`.test.ts`) | `packages/*/src/**/*.test.ts` | `vitest.config.ts` | Internal logic, edge cases |
| BDD (`.steps.ts`) | `packages/*/src/steps/*.steps.ts` | `vitest.config.bdd.ts` | Behavior contracts vs `.feature` specs |

### When to run what

| Situation | Command |
|-----------|---------|
| Quick check during dev | `/code-quality test unit` |
| Verifying behavior contracts | `/code-quality test bdd` |
| Before committing | `/code-quality validate` |
| Single package focus | `/code-quality test core` |
| After fixing lint/types only | `bun lint:quiet && bun typecheck:quiet` |

## Coverage

```
/code-quality coverage core
/code-quality coverage schema
/code-quality coverage validation
/code-quality coverage query
```

Excludes test files. Focus on source coverage only.

## Output Levels

| Level | Suffix | Use case |
|-------|--------|----------|
| Normal | _(none)_ | Interactive development |
| Quiet | `:quiet` | Claude assistant, CI |
| Silent | `:silent` | Pre-commit hooks |

Quiet variants: `bun test:quiet`, `bun lint:quiet`, `bun typecheck:quiet`, `bun knip:quiet`, `bun eslint:quiet`


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### scripts/__tests__/coverage.test.ts

```typescript
import { execSync } from "node:child_process";
import { join } from "node:path";
import { describe, expect, it } from "vitest";

const SCRIPT = join(__dirname, "..", "coverage.sh");
const ROOT = join(__dirname, "../../../../..");

function run(args: string): { stdout: string; stderr: string; exitCode: number } {
  try {
    const stdout = execSync(`bash ${SCRIPT} ${args}`, {
      cwd: ROOT,
      encoding: "utf-8",
      timeout: 60000,
      stdio: ["pipe", "pipe", "pipe"],
    });
    return { stdout, stderr: "", exitCode: 0 };
  } catch (e: any) {
    return {
      stdout: e.stdout || "",
      stderr: e.stderr || "",
      exitCode: e.status ?? 1,
    };
  }
}

describe("coverage.sh", () => {
  it("should fail without arguments", () => {
    const result = run("");
    expect(result.exitCode).not.toBe(0);
  });

  it("should reject invalid package names", () => {
    const result = run("nonexistent");
    expect(result.exitCode).not.toBe(0);
    expect(result.stdout + result.stderr).toContain("Invalid package");
  });

  it("should accept valid package names", () => {
    const result = run("core");
    expect(result.stdout).toContain("Generating coverage for @schmock/core");
  });
});

```

### scripts/__tests__/test.test.ts

```typescript
import { execSync } from "node:child_process";
import { join } from "node:path";
import { describe, expect, it } from "vitest";

const SCRIPT = join(__dirname, "..", "test.sh");
const ROOT = join(__dirname, "../../../../..");

function run(args: string): { stdout: string; stderr: string; exitCode: number } {
  try {
    const stdout = execSync(`bash ${SCRIPT} ${args}`, {
      cwd: ROOT,
      encoding: "utf-8",
      timeout: 120000,
      stdio: ["pipe", "pipe", "pipe"],
    });
    return { stdout, stderr: "", exitCode: 0 };
  } catch (e: any) {
    return {
      stdout: e.stdout || "",
      stderr: e.stderr || "",
      exitCode: e.status ?? 1,
    };
  }
}

describe("test.sh", () => {
  it("should fail without arguments", () => {
    const result = run("");
    expect(result.exitCode).not.toBe(0);
  });

  it("should reject unknown targets", () => {
    const result = run("foobar");
    expect(result.exitCode).not.toBe(0);
    expect(result.stdout + result.stderr).toContain("Unknown target");
  });

  it("should accept 'all' target", () => {
    const result = run("all");
    expect(result.stdout).toContain("Running full test suite");
  });

  it("should accept 'unit' target", () => {
    const result = run("unit");
    expect(result.stdout).toContain("Running unit tests");
  });

  it("should accept 'bdd' target", () => {
    const result = run("bdd");
    expect(result.stdout).toContain("Running BDD tests");
  });

  it("should accept package names", () => {
    for (const pkg of ["core", "schema", "express", "angular"]) {
      const result = run(pkg);
      expect(result.stdout).toContain(`Running tests for @schmock/${pkg}`);
    }
  });
});

```

### scripts/__tests__/validate.test.ts

```typescript
import { execSync } from "node:child_process";
import { join } from "node:path";
import { describe, expect, it } from "vitest";

const SCRIPT = join(__dirname, "..", "validate.sh");
const ROOT = join(__dirname, "../../../../..");

function run(): { stdout: string; stderr: string; exitCode: number } {
  try {
    const stdout = execSync(`bash ${SCRIPT}`, {
      cwd: ROOT,
      encoding: "utf-8",
      timeout: 180000,
      stdio: ["pipe", "pipe", "pipe"],
    });
    return { stdout, stderr: "", exitCode: 0 };
  } catch (e: any) {
    return {
      stdout: e.stdout || "",
      stderr: e.stderr || "",
      exitCode: e.status ?? 1,
    };
  }
}

describe("validate.sh", () => {
  it("should run all validation stages and print results", () => {
    const result = run();
    const output = result.stdout + result.stderr;
    // Should have the stage headers
    expect(output).toContain("Lint");
    expect(output).toContain("Typecheck");
    expect(output).toContain("Unit");
    expect(output).toContain("BDD");
    // Should have the results summary
    expect(output).toContain("Results");
    expect(output).toContain("Passed:");
  });
});

```

### scripts/coverage.sh

```bash
#!/usr/bin/env bash
set -euo pipefail

# Generate per-package coverage report.
#
# Usage:
#   bash coverage.sh <package>
#
# Example:
#   bash coverage.sh core
#   bash coverage.sh schema

PKG="${1:?Usage: coverage.sh <package>}"
VALID_PACKAGES="core schema express angular validation query"

if ! echo "$VALID_PACKAGES" | grep -qw "$PKG"; then
  echo "Invalid package: ${PKG}"
  echo "Valid packages: ${VALID_PACKAGES}"
  exit 1
fi

PKG_DIR="packages/${PKG}"

if [ ! -d "$PKG_DIR" ]; then
  echo "Package directory not found: ${PKG_DIR}"
  exit 1
fi

echo "Generating coverage for @schmock/${PKG}..."
cd "$PKG_DIR"

bunx vitest run \
  --coverage \
  --coverage.include='src/**/*.ts' \
  --coverage.exclude='src/**/*.test.ts' \
  --coverage.exclude='src/**/*.steps.ts' \
  --coverage.exclude='src/steps/**'

```

### scripts/test.sh

```bash
#!/usr/bin/env bash
set -euo pipefail

# Run tests for Schmock packages.
#
# Usage:
#   bash test.sh all        # typecheck + unit + BDD
#   bash test.sh unit       # unit tests only
#   bash test.sh bdd        # BDD tests only
#   bash test.sh <package>  # tests for a specific package (core, schema, express, angular)

TARGET="${1:?Usage: test.sh all|unit|bdd|<package>}"

case "$TARGET" in
  all)
    echo "Running full test suite (typecheck + unit + BDD)..."
    bun test:all:quiet
    ;;
  unit)
    echo "Running unit tests..."
    bun test:unit:quiet
    ;;
  bdd)
    echo "Running BDD tests..."
    bun test:bdd:quiet
    ;;
  core|schema|express|angular|validation|query)
    echo "Running tests for @schmock/${TARGET}..."
    bun run --filter "@schmock/${TARGET}" test
    ;;
  *)
    echo "Unknown target: ${TARGET}"
    echo "Usage: test.sh all|unit|bdd|<package>"
    echo "Packages: core, schema, express, angular, validation, query"
    exit 1
    ;;
esac

```

### scripts/validate.sh

```bash
#!/usr/bin/env bash
set -uo pipefail

# Full quality validation gate for Schmock.
# Runs all 7 stages sequentially and reports pass/fail with fix hints.

PASS=0
FAIL=0
RESULTS=()
FIXES=()

run_stage() {
  local name="$1"
  local fix_hint="$2"
  shift 2
  echo "━━━ ${name} ━━━"
  if "$@" 2>&1; then
    RESULTS+=("✓ ${name}")
    ((PASS++))
  else
    RESULTS+=("✗ ${name}")
    FIXES+=("  ${name}: ${fix_hint}")
    ((FAIL++))
  fi
  echo ""
}

run_stage "Lint"      "Run 'bun lint:fix' to auto-fix, then review remaining issues in biome output" \
  bun lint:quiet

run_stage "Typecheck" "Run 'bun typecheck' for full error output, fix type errors in reported files" \
  bun typecheck:quiet

run_stage "Knip"      "Run 'bun knip' to see dead exports/unused deps, remove or re-export them" \
  bun knip:quiet

run_stage "ESLint"    "Run 'bun eslint' to see 'as' casts, replace with type guards/runtime validators" \
  bun eslint:quiet

run_stage "Unit"      "Run 'bun test:unit' for full output, fix failing assertions" \
  bun test:unit:quiet

run_stage "BDD"       "Run 'bun test:bdd' for full output, check step text matches .feature files" \
  bun test:bdd:quiet

run_stage "Bench"     "Run 'bun bench' for full output, check for throughput regressions" \
  bun bench

echo "━━━ Results ━━━"
for r in "${RESULTS[@]}"; do
  echo "  ${r}"
done
echo ""

if [ "$FAIL" -gt 0 ]; then
  echo "━━━ How to fix ━━━"
  for f in "${FIXES[@]}"; do
    echo "${f}"
  done
  echo ""
  echo "Passed: ${PASS}  Failed: ${FAIL}"
  exit 1
else
  echo "Passed: ${PASS}  Failed: ${FAIL}"
  echo "All gates passed — ready to commit."
fi

```