1k-code-quality

Code Quality

Linting, documentation, and general code quality standards for OneKey.

Lint Commands

# Agent pre-commit gate (fast, only staged files)
yarn agent:check --profile commit

# Agent PR readiness gate (local staged checks + GitHub CI/review summary)
yarn agent:check --profile pr

# CI only (full project check)
yarn lint        # Comprehensive: TypeScript, oxlint, folder structure, i18n
yarn lint:only   # Oxlint and oxfmt
yarn tsc:only    # Full type check
yarn lint:agent-context # Skill metadata and startup-context budgets

Note: yarn lint is for CI only. For agent workflows, always use yarn agent:check first; use lower-level commands only when debugging the log path reported by agent:check.

This repository uses oxlint, not ESLint, for active lint validation. Do not run yarn eslint, npx eslint, or node_modules/.bin/eslint; those entries are legacy compatibility remnants and yarn eslint runs a whole-repository auto-fix. For a read-only targeted diagnostic, run:

npx oxlint --tsconfig ./tsconfig.json --type-aware packages/example/src/file.ts --deny-warnings

Pre-Commit Workflow

For fast pre-commit validation:

yarn agent:check --profile commit

Common Lint Fixes

// Unused variable - prefix with underscore
const { used, unused } = obj;     // ❌ Error: 'unused' is defined but never used
const { used, unused: _unused } = obj;  // ✅ OK

// Unused parameter - prefix with underscore
function foo(used: string, unused: number) {}     // ❌ Error
function foo(used: string, _unused: number) {}    // ✅ OK

// Floating promise - add void or await
someAsyncFunction();        // ❌ Error: Promises must be awaited
void someAsyncFunction();   // ✅ OK (fire-and-forget)
await someAsyncFunction();  // ✅ OK (wait for result)

Language Requirements

All comments must be written in English:

// ✅ GOOD: English comment
// Calculate the total balance including pending transactions

// ❌ BAD: Chinese comment
// 计算总余额，包括待处理的交易

// ✅ GOOD: JSDoc in English
/**
 * Fetches user balance from the blockchain.
 * @param address - The wallet address to query
 * @returns The balance in native token units
 */
async function fetchBalance(address: string): Promise<bigint> {
  // ...
}

When to Comment

// ✅ GOOD: Explain non-obvious logic
// Use 1.5x gas limit to account for estimation variance on this chain
const gasLimit = estimatedGas * 1.5n;

// ✅ GOOD: Explain business logic
// Premium users get 50% discount on transaction fees
const fee = isPremium ? baseFee * 0.5 : baseFee;

// ❌ BAD: Obvious comment
// Set the value to 5
const value = 5;

Development Principles

Single Responsibility

Each function should perform a single, atomic task:

// ✅ GOOD: Single responsibility
async function fetchUserBalance(userId: string): Promise<Balance> {
  const user = await getUser(userId);
  return await getBalanceForAddress(user.address);
}

// ❌ BAD: Multiple responsibilities
async function fetchUserBalanceAndUpdateUI(userId: string) {
  const user = await getUser(userId);
  const balance = await getBalanceForAddress(user.address);
  setBalanceState(balance);
  showNotification('Balance updated');
  logAnalytics('balance_fetched');
}

Avoid Over-Abstraction

Don't create helpers for one-time operations:

// ❌ BAD: Over-abstracted
const createUserFetcher = (config: Config) => {
  return (userId: string) => {
    return fetchWithConfig(config, `/users/${userId}`);
  };
};
const fetchUser = createUserFetcher(defaultConfig);
const user = await fetchUser(userId);

// ✅ GOOD: Simple and direct
const user = await fetch(`/api/users/${userId}`).then(r => r.json());

Detailed Guides

Code Quality Standards

See code-quality.md for comprehensive guidelines:

• Linting commands and pre-commit workflow
• Comment and documentation standards
• Language requirements (English only)
• Single responsibility principle
• Avoiding over-abstraction
• Consistent naming conventions
• Code quality checklist

Fixing Lint Warnings

See fix-lint.md for complete lint fix workflow:

• Analyzing lint warnings
• Categorizing lint errors
• Common fix patterns by category
• Spellcheck fixes
• Unused variable/parameter handling
• Automated fix strategies
• Testing after fixes

Spellcheck

If a technical term triggers spellcheck errors:

# Check if word exists
grep -i "yourword" development/spellCheckerSkipWords.txt

# Add if not present (ask team lead first)
echo "yourword" >> development/spellCheckerSkipWords.txt

Agent Context Harness

yarn lint:agent-context enforces repository skill discovery and startup context budgets. Configuration lives in development/lint/agent-context.config.json. When adding or restructuring a skill, keep detailed guidance in references, use Codex explicit policy for operational workflows, and stay within the configured catalog and instruction budgets.

Checklist

Pre-commit

• yarn agent:check --profile commit passes

Code Quality

• All comments are in English
• No commented-out code committed
• Functions have single responsibility
• No unnecessary abstractions
• Consistent naming conventions

Related Skills

• /1k-sentry - Sentry error analysis and fixes
• /1k-test-version - Test version creation workflow
• /1k-coding-patterns - General coding patterns