storkit/.story_kit/CODE_QUALITY_CHECKLIST.md

Code Quality Checklist

This document provides a quick reference for code quality checks that MUST be performed before completing any story.

Pre-Completion Checklist

Before asking for user acceptance in Step 4 (Verification), ALL of the following must pass:

Rust Backend

# 1. Run Clippy (linter)
cd src-tauri
cargo clippy --all-targets --all-features
# Expected: 0 errors, 0 warnings

# 2. Run cargo check (compilation)
cargo check
# Expected: successful compilation

# 3. Run tests
cargo test
# Expected: all tests pass

Result Required: ✅ 0 errors, 0 warnings, all tests pass

TypeScript Frontend

# 1. Run TypeScript compiler check (type errors)
npx tsc --noEmit
# Expected: 0 errors

# 2. Run Biome check (linter + formatter)
npx @biomejs/biome check src/
# Expected: 0 errors, 0 warnings

# 3. Apply fixes if needed
npx @biomejs/biome check --write src/
npx @biomejs/biome check --write --unsafe src/  # for unsafe fixes

# 4. Build
npm run build
# Expected: successful build

Result Required: ✅ 0 errors, 0 warnings, successful build

Common Biome Issues and Fixes

1. noExplicitAny - No any types

Bad:

const handler = (data: any) => { ... }

Good:

const handler = (data: { className?: string; children?: React.ReactNode; [key: string]: unknown }) => { ... }

2. noArrayIndexKey - Don't use array index as key

Bad:

{items.map((item, idx) => <div key={idx}>...</div>)}

Good:

{items.map((item, idx) => <div key={`item-${idx}-${item.id}`}>...</div>)}

3. useButtonType - Always specify button type

Bad:

<button onClick={handler}>Click</button>

Good:

<button type="button" onClick={handler}>Click</button>

4. noAssignInExpressions - No assignments in expressions

Bad:

onMouseOver={(e) => (e.currentTarget.style.background = "#333")}

Good:

onMouseOver={(e) => {
  e.currentTarget.style.background = "#333";
}}

5. useKeyWithMouseEvents - Add keyboard alternatives

Bad:

<button onMouseOver={handler} onMouseOut={handler2}>...</button>

Good:

<button 
  onMouseOver={handler} 
  onMouseOut={handler2}
  onFocus={handler}
  onBlur={handler2}
>...</button>

6. useImportType - Import types with import type

Bad:

import { Message, Config } from "./types";

Good:

import type { Message, Config } from "./types";

Common Clippy Issues and Fixes

1. Unused variables

Bad:

} catch (e) {

Good:

} catch (_e) {  // prefix with underscore

2. Dead code warnings

Option 1: Remove the code if truly unused

Option 2: Mark as allowed if used conditionally

#[allow(dead_code)]
struct UnusedStruct {
    field: String,
}

3. Explicit return

Bad:

fn get_value() -> i32 {
    return 42;
}

Good:

fn get_value() -> i32 {
    42
}

Quick Verification Script

Save this as check.sh and run before every story completion:

#!/bin/bash
set -e

echo "=== Checking Rust Backend ==="
cd src-tauri
cargo clippy --all-targets --all-features
cargo check
cargo test
cd ..

echo ""
echo "=== Checking TypeScript Frontend ==="
npx tsc --noEmit
npx @biomejs/biome check src/
npm run build

echo ""
echo "✅ ALL CHECKS PASSED!"

Zero Tolerance Policy

• No exceptions: All errors and warnings MUST be fixed
• No workarounds: Don't disable rules unless absolutely necessary
• No "will fix later": Fix immediately before story completion
• User must see clean output: When running checks, show clean results to user

When Rules Conflict with Requirements

If a linting rule conflicts with a legitimate requirement:

1. Document why the rule must be bypassed
2. Use the minimal scope for the exception (line/function, not file)
3. Add a comment explaining the exception
4. Get user approval

Example:

// Biome requires proper types, but react-markdown types are incompatible
// Using unknown for compatibility
const code = ({ className, children }: { className?: string; children?: React.ReactNode; [key: string]: unknown }) => {
  ...
}

Integration with SDTW

This checklist is part of Step 4: Verification in the Story-Driven Test Workflow.

You cannot proceed to story acceptance without passing all checks.