[ { "path": ".github/workflows/react-best-practices-ci.yml", "content": "name: React Best Practices CI\n\non:\n push:\n branches: [main]\n paths:\n - 'skills/react-best-practices/**'\n - 'packages/react-best-practices-build/**'\n pull_request:\n branches: [main]\n paths:\n - 'skills/react-best-practices/**'\n - 'packages/react-best-practices-build/**'\n\njobs:\n validate:\n runs-on: ubuntu-latest\n defaults:\n run:\n working-directory: packages/react-best-practices-build\n steps:\n - uses: actions/checkout@v4\n - uses: pnpm/action-setup@v2\n with:\n version: 10.24.0\n - uses: actions/setup-node@v4\n with:\n node-version: '20'\n cache: 'pnpm'\n cache-dependency-path: packages/react-best-practices-build/pnpm-lock.yaml\n - run: pnpm install\n - run: pnpm validate\n - run: pnpm build\n" }, { "path": ".gitignore", "content": ".DS_Store\n.vercel\n.env*.local\n" }, { "path": "AGENTS.md", "content": "# AGENTS.md\n\nThis file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.\n\n## Repository Overview\n\nA collection of skills for Claude.ai and Claude Code for working with Vercel deployments. Skills are packaged instructions and scripts that extend Claude's capabilities.\n\n## Creating a New Skill\n\n### Directory Structure\n\n```\nskills/\n {skill-name}/ # kebab-case directory name\n SKILL.md # Required: skill definition\n scripts/ # Required: executable scripts\n {script-name}.sh # Bash scripts (preferred)\n {skill-name}.zip # Required: packaged for distribution\n```\n\n### Naming Conventions\n\n- **Skill directory**: `kebab-case` (e.g., `vercel-deploy`, `log-monitor`)\n- **SKILL.md**: Always uppercase, always this exact filename\n- **Scripts**: `kebab-case.sh` (e.g., `deploy.sh`, `fetch-logs.sh`)\n- **Zip file**: Must match directory name exactly: `{skill-name}.zip`\n\n### SKILL.md Format\n\n```markdown\n---\nname: {skill-name}\ndescription: {One sentence describing when to use this skill. Include trigger phrases like \"Deploy my app\", \"Check logs\", etc.}\n---\n\n# {Skill Title}\n\n{Brief description of what the skill does.}\n\n## How It Works\n\n{Numbered list explaining the skill's workflow}\n\n## Usage\n\n```bash\nbash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]\n```\n\n**Arguments:**\n- `arg1` - Description (defaults to X)\n\n**Examples:**\n{Show 2-3 common usage patterns}\n\n## Output\n\n{Show example output users will see}\n\n## Present Results to User\n\n{Template for how Claude should format results when presenting to users}\n\n## Troubleshooting\n\n{Common issues and solutions, especially network/permissions errors}\n```\n\n### Best Practices for Context Efficiency\n\nSkills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:\n\n- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files\n- **Write specific descriptions** — helps the agent know exactly when to activate the skill\n- **Use progressive disclosure** — reference supporting files that get read only when needed\n- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)\n- **File references work one level deep** — link directly from SKILL.md to supporting files\n\n### Script Requirements\n\n- Use `#!/bin/bash` shebang\n- Use `set -e` for fail-fast behavior\n- Write status messages to stderr: `echo \"Message\" >&2`\n- Write machine-readable output (JSON) to stdout\n- Include a cleanup trap for temp files\n- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`\n\n### Creating the Zip Package\n\nAfter creating or updating a skill:\n\n```bash\ncd skills\nzip -r {skill-name}.zip {skill-name}/\n```\n\n### End-User Installation\n\nDocument these two installation methods for users:\n\n**Claude Code:**\n```bash\ncp -r skills/{skill-name} ~/.claude/skills/\n```\n\n**claude.ai:**\nAdd the skill to project knowledge or paste SKILL.md contents into the conversation.\n\nIf the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.\n" }, { "path": "README.md", "content": "# Agent Skills\n\nA collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities.\n\nSkills follow the [Agent Skills](https://agentskills.io/) format.\n\n## Available Skills\n\n### react-best-practices\n\nReact and Next.js performance optimization guidelines from Vercel Engineering. Contains 40+ rules across 8 categories, prioritized by impact.\n\n**Use when:**\n- Writing new React components or Next.js pages\n- Implementing data fetching (client or server-side)\n- Reviewing code for performance issues\n- Optimizing bundle size or load times\n\n**Categories covered:**\n- Eliminating waterfalls (Critical)\n- Bundle size optimization (Critical)\n- Server-side performance (High)\n- Client-side data fetching (Medium-High)\n- Re-render optimization (Medium)\n- Rendering performance (Medium)\n- JavaScript micro-optimizations (Low-Medium)\n\n### web-design-guidelines\n\nReview UI code for compliance with web interface best practices. Audits your code for 100+ rules covering accessibility, performance, and UX.\n\n**Use when:**\n- \"Review my UI\"\n- \"Check accessibility\"\n- \"Audit design\"\n- \"Review UX\"\n- \"Check my site against best practices\"\n\n**Categories covered:**\n- Accessibility (aria-labels, semantic HTML, keyboard handlers)\n- Focus States (visible focus, focus-visible patterns)\n- Forms (autocomplete, validation, error handling)\n- Animation (prefers-reduced-motion, compositor-friendly transforms)\n- Typography (curly quotes, ellipsis, tabular-nums)\n- Images (dimensions, lazy loading, alt text)\n- Performance (virtualization, layout thrashing, preconnect)\n- Navigation & State (URL reflects state, deep-linking)\n- Dark Mode & Theming (color-scheme, theme-color meta)\n- Touch & Interaction (touch-action, tap-highlight)\n- Locale & i18n (Intl.DateTimeFormat, Intl.NumberFormat)\n\n### react-native-guidelines\n\nReact Native best practices optimized for AI agents. Contains 16 rules across 7 sections covering performance, architecture, and platform-specific patterns.\n\n**Use when:**\n- Building React Native or Expo apps\n- Optimizing mobile performance\n- Implementing animations or gestures\n- Working with native modules or platform APIs\n\n**Categories covered:**\n- Performance (Critical) - FlashList, memoization, heavy computation\n- Layout (High) - flex patterns, safe areas, keyboard handling\n- Animation (High) - Reanimated, gesture handling\n- Images (Medium) - expo-image, caching, lazy loading\n- State Management (Medium) - Zustand patterns, React Compiler\n- Architecture (Medium) - monorepo structure, imports\n- Platform (Medium) - iOS/Android specific patterns\n\n### composition-patterns\n\nReact composition patterns that scale. Helps avoid boolean prop proliferation through compound components, state lifting, and internal composition.\n\n**Use when:**\n- Refactoring components with many boolean props\n- Building reusable component libraries\n- Designing flexible APIs\n- Reviewing component architecture\n\n**Patterns covered:**\n- Extracting compound components\n- Lifting state to reduce props\n- Composing internals for flexibility\n- Avoiding prop drilling\n\n### vercel-deploy-claimable\n\nDeploy applications and websites to Vercel instantly. Designed for use with claude.ai and Claude Desktop to enable deployments directly from conversations. Deployments are \"claimable\" - users can transfer ownership to their own Vercel account.\n\n**Use when:**\n- \"Deploy my app\"\n- \"Deploy this to production\"\n- \"Push this live\"\n- \"Deploy and give me the link\"\n\n**Features:**\n- Auto-detects 40+ frameworks from `package.json`\n- Returns preview URL (live site) and claim URL (transfer ownership)\n- Handles static HTML projects automatically\n- Excludes `node_modules` and `.git` from uploads\n\n**How it works:**\n1. Packages your project into a tarball\n2. Detects framework (Next.js, Vite, Astro, etc.)\n3. Uploads to deployment service\n4. Returns preview URL and claim URL\n\n**Output:**\n```\nDeployment successful!\n\nPreview URL: https://skill-deploy-abc123.vercel.app\nClaim URL: https://vercel.com/claim-deployment?code=...\n```\n\n## Installation\n\n```bash\nnpx skills add vercel-labs/agent-skills\n```\n\n## Usage\n\nSkills are automatically available once installed. The agent will use them when relevant tasks are detected.\n\n**Examples:**\n```\nDeploy my app\n```\n```\nReview this React component for performance issues\n```\n```\nHelp me optimize this Next.js page\n```\n\n## Skill Structure\n\nEach skill contains:\n- `SKILL.md` - Instructions for the agent\n- `scripts/` - Helper scripts for automation (optional)\n- `references/` - Supporting documentation (optional)\n\n## License\n\nMIT\n" }, { "path": "packages/react-best-practices-build/.gitignore", "content": "node_modules/\n" }, { "path": "packages/react-best-practices-build/package.json", "content": "{\n \"name\": \"react-best-practices-build\",\n \"version\": \"1.0.0\",\n \"description\": \"Build tooling for React Best Practices and React Native Guidelines skills\",\n \"type\": \"module\",\n \"scripts\": {\n \"build\": \"pnpm build-agents && pnpm extract-tests\",\n \"build-agents\": \"tsx src/build.ts\",\n \"build-all\": \"tsx src/build.ts --all\",\n \"build-react\": \"tsx src/build.ts --skill=react-best-practices\",\n \"build-rn\": \"tsx src/build.ts --skill=react-native-skills\",\n \"build-composition\": \"tsx src/build.ts --skill=composition-patterns\",\n \"validate\": \"tsx src/validate.ts\",\n \"extract-tests\": \"tsx src/extract-tests.ts\",\n \"migrate\": \"tsx src/migrate.ts\",\n \"dev\": \"pnpm build && pnpm validate\"\n },\n \"keywords\": [\n \"react\",\n \"performance\",\n \"guidelines\",\n \"llm\",\n \"agents\"\n ],\n \"license\": \"MIT\",\n \"devDependencies\": {\n \"@types/node\": \"^20.0.0\",\n \"tsx\": \"^4.7.0\",\n \"typescript\": \"^5.3.0\"\n }\n}\n" }, { "path": "packages/react-best-practices-build/src/build.ts", "content": "#!/usr/bin/env node\n/**\n * Build script to compile individual rule files into AGENTS.md\n */\n\nimport { readdir, readFile, writeFile } from 'fs/promises'\nimport { join } from 'path'\nimport { Rule, Section, GuidelinesDocument, ImpactLevel } from './types.js'\nimport { parseRuleFile, RuleFile } from './parser.js'\nimport { SKILLS, SkillConfig, DEFAULT_SKILL } from './config.js'\n\n// Parse command line arguments\nconst args = process.argv.slice(2)\nconst upgradeVersion = args.includes('--upgrade-version')\nconst skillArg = args.find((arg) => arg.startsWith('--skill='))\nconst skillName = skillArg ? skillArg.split('=')[1] : null\nconst buildAll = args.includes('--all')\n\n/**\n * Increment a semver-style version string (e.g., \"0.1.0\" -> \"0.1.1\", \"1.0\" -> \"1.1\")\n */\nfunction incrementVersion(version: string): string {\n const parts = version.split('.').map(Number)\n // Increment the last part\n parts[parts.length - 1]++\n return parts.join('.')\n}\n\n/**\n * Generate markdown from rules\n */\nfunction generateMarkdown(\n sections: Section[],\n metadata: {\n version: string\n organization: string\n date: string\n abstract: string\n references?: string[]\n },\n skillConfig: SkillConfig\n): string {\n let md = `# ${skillConfig.title}\\n\\n`\n md += `**Version ${metadata.version}** \\n`\n md += `${metadata.organization} \\n`\n md += `${metadata.date}\\n\\n`\n md += `> **Note:** \\n`\n md += `> This document is mainly for agents and LLMs to follow when maintaining, \\n`\n md += `> generating, or refactoring ${skillConfig.description}. Humans \\n`\n md += `> may also find it useful, but guidance here is optimized for automation \\n`\n md += `> and consistency by AI-assisted workflows.\\n\\n`\n md += `---\\n\\n`\n md += `## Abstract\\n\\n`\n md += `${metadata.abstract}\\n\\n`\n md += `---\\n\\n`\n md += `## Table of Contents\\n\\n`\n\n // Generate TOC\n sections.forEach((section) => {\n md += `${section.number}. [${section.title}](#${\n section.number\n }-${section.title.toLowerCase().replace(/\\s+/g, '-')}) — **${\n section.impact\n }**\\n`\n section.rules.forEach((rule) => {\n // GitHub generates anchors from the full heading text: \"1.1 Title\" -> \"#11-title\"\n const anchor = `${rule.id} ${rule.title}`\n .toLowerCase()\n .replace(/\\s+/g, '-')\n .replace(/[^\\w-]/g, '') // Remove special characters except hyphens\n md += ` - ${rule.id} [${rule.title}](#${anchor})\\n`\n })\n })\n\n md += `\\n---\\n\\n`\n\n // Generate sections\n sections.forEach((section) => {\n md += `## ${section.number}. ${section.title}\\n\\n`\n md += `**Impact: ${section.impact}${\n section.impactDescription ? ` (${section.impactDescription})` : ''\n }**\\n\\n`\n if (section.introduction) {\n md += `${section.introduction}\\n\\n`\n }\n\n section.rules.forEach((rule) => {\n md += `### ${rule.id} ${rule.title}\\n\\n`\n md += `**Impact: ${rule.impact}${\n rule.impactDescription ? ` (${rule.impactDescription})` : ''\n }**\\n\\n`\n md += `${rule.explanation}\\n\\n`\n\n rule.examples.forEach((example) => {\n if (example.description) {\n md += `**${example.label}: ${example.description}**\\n\\n`\n } else {\n md += `**${example.label}:**\\n\\n`\n }\n // Only generate code block if there's actual code\n if (example.code && example.code.trim()) {\n md += `\\`\\`\\`${example.language || 'typescript'}\\n`\n md += `${example.code}\\n`\n md += `\\`\\`\\`\\n\\n`\n }\n if (example.additionalText) {\n md += `${example.additionalText}\\n\\n`\n }\n })\n\n if (rule.references && rule.references.length > 0) {\n md += `Reference: ${rule.references\n .map((ref) => `[${ref}](${ref})`)\n .join(', ')}\\n\\n`\n }\n })\n\n md += `---\\n\\n`\n })\n\n // Add references section\n if (metadata.references && metadata.references.length > 0) {\n md += `## References\\n\\n`\n metadata.references.forEach((ref, i) => {\n md += `${i + 1}. [${ref}](${ref})\\n`\n })\n }\n\n return md\n}\n\n/**\n * Build a single skill\n */\nasync function buildSkill(skillConfig: SkillConfig) {\n console.log(`\\nBuilding ${skillConfig.name}...`)\n console.log(` Rules directory: ${skillConfig.rulesDir}`)\n console.log(` Output file: ${skillConfig.outputFile}`)\n\n // Read all rule files (exclude files starting with _ and README.md)\n const files = await readdir(skillConfig.rulesDir)\n const ruleFiles = files\n .filter((f) => f.endsWith('.md') && !f.startsWith('_') && f !== 'README.md')\n .sort() // Sort filenames for consistent ordering across systems\n\n const ruleData: RuleFile[] = []\n for (const file of ruleFiles) {\n const filePath = join(skillConfig.rulesDir, file)\n try {\n const parsed = await parseRuleFile(filePath, skillConfig.sectionMap)\n ruleData.push(parsed)\n } catch (error) {\n console.error(` Error parsing ${file}:`, error)\n }\n }\n\n // Group rules by section\n const sectionsMap = new Map()\n\n ruleData.forEach(({ section, rule }) => {\n if (!sectionsMap.has(section)) {\n sectionsMap.set(section, {\n number: section,\n title: `Section ${section}`, // Will be overridden by section metadata\n impact: rule.impact,\n rules: [],\n })\n }\n sectionsMap.get(section)!.rules.push(rule)\n })\n\n // Sort rules within each section by title (using en-US locale for consistency across environments)\n sectionsMap.forEach((section) => {\n section.rules.sort((a, b) =>\n a.title.localeCompare(b.title, 'en-US', { sensitivity: 'base' })\n )\n\n // Assign IDs based on sorted order\n section.rules.forEach((rule, index) => {\n rule.id = `${section.number}.${index + 1}`\n rule.subsection = index + 1\n })\n })\n\n // Convert to array and sort\n const sections = Array.from(sectionsMap.values()).sort(\n (a, b) => a.number - b.number\n )\n\n // Read section metadata from consolidated _sections.md file\n const sectionsFile = join(skillConfig.rulesDir, '_sections.md')\n try {\n const sectionsContent = await readFile(sectionsFile, 'utf-8')\n\n // Parse sections using regex to match each section block\n const sectionBlocks = sectionsContent\n .split(/(?=^## \\d+\\. )/m)\n .filter(Boolean)\n\n for (const block of sectionBlocks) {\n // Extract section number and title, removing section ID in parentheses\n const headerMatch = block.match(/^## (\\d+)\\.\\s+(.+?)(?:\\s+\\([^)]+\\))?$/m)\n if (!headerMatch) continue\n\n const sectionNumber = parseInt(headerMatch[1])\n const sectionTitle = headerMatch[2].trim() // Strip (id) for output\n\n // Extract impact (format: **Impact:** CRITICAL)\n const impactMatch = block.match(/\\*\\*Impact:\\*\\*\\s+(\\w+(?:-\\w+)?)/i)\n const impactLevel = impactMatch\n ? (impactMatch[1].toUpperCase().replace(/-/g, '-') as ImpactLevel)\n : 'MEDIUM'\n\n // Extract description (format: **Description:** text)\n const descMatch = block.match(/\\*\\*Description:\\*\\*\\s+(.+?)(?=\\n\\n##|$)/s)\n const description = descMatch ? descMatch[1].trim() : ''\n\n // Update section if it exists\n const section = sections.find((s) => s.number === sectionNumber)\n if (section) {\n section.title = sectionTitle\n section.impact = impactLevel\n section.introduction = description\n }\n }\n } catch (error) {\n console.warn(' Warning: Could not read _sections.md, using defaults')\n }\n\n // Read metadata\n let metadata\n try {\n const metadataContent = await readFile(skillConfig.metadataFile, 'utf-8')\n metadata = JSON.parse(metadataContent)\n } catch {\n metadata = {\n version: '1.0.0',\n organization: 'Engineering',\n date: new Date().toLocaleDateString('en-US', {\n month: 'long',\n year: 'numeric',\n }),\n abstract: `Performance optimization guide for ${skillConfig.description}, ordered by impact.`,\n }\n }\n\n // Upgrade version if flag is passed\n if (upgradeVersion) {\n const oldVersion = metadata.version\n metadata.version = incrementVersion(oldVersion)\n console.log(` Upgrading version: ${oldVersion} -> ${metadata.version}`)\n\n // Write updated metadata.json\n await writeFile(\n skillConfig.metadataFile,\n JSON.stringify(metadata, null, 2) + '\\n',\n 'utf-8'\n )\n console.log(` ✓ Updated metadata.json`)\n\n // Update SKILL.md frontmatter if it exists\n const skillFile = join(skillConfig.skillDir, 'SKILL.md')\n try {\n const skillContent = await readFile(skillFile, 'utf-8')\n const updatedSkillContent = skillContent.replace(\n /^(---[\\s\\S]*?version:\\s*)\"[^\"]*\"([\\s\\S]*?---)$/m,\n `$1\"${metadata.version}\"$2`\n )\n await writeFile(skillFile, updatedSkillContent, 'utf-8')\n console.log(` ✓ Updated SKILL.md`)\n } catch {\n // SKILL.md doesn't exist, skip\n }\n }\n\n // Generate markdown\n const markdown = generateMarkdown(sections, metadata, skillConfig)\n\n // Write output\n await writeFile(skillConfig.outputFile, markdown, 'utf-8')\n\n console.log(\n ` ✓ Built AGENTS.md with ${sections.length} sections and ${ruleData.length} rules`\n )\n}\n\n/**\n * Main build function\n */\nasync function build() {\n try {\n console.log('Building AGENTS.md from rules...')\n\n if (buildAll) {\n // Build all skills\n for (const skill of Object.values(SKILLS)) {\n await buildSkill(skill)\n }\n } else if (skillName) {\n // Build specific skill\n const skill = SKILLS[skillName]\n if (!skill) {\n console.error(`Unknown skill: ${skillName}`)\n console.error(`Available skills: ${Object.keys(SKILLS).join(', ')}`)\n process.exit(1)\n }\n await buildSkill(skill)\n } else {\n // Build default skill (backwards compatibility)\n await buildSkill(SKILLS[DEFAULT_SKILL])\n }\n\n console.log('\\n✓ Build complete')\n } catch (error) {\n console.error('Build failed:', error)\n process.exit(1)\n }\n}\n\nbuild()\n" }, { "path": "packages/react-best-practices-build/src/config.ts", "content": "/**\n * Configuration for the build tooling\n */\n\nimport { join, dirname } from 'path'\nimport { fileURLToPath } from 'url'\n\nconst __dirname = dirname(fileURLToPath(import.meta.url))\n\n// Base paths\nexport const SKILLS_DIR = join(__dirname, '../../..', 'skills')\nexport const BUILD_DIR = join(__dirname, '..')\n\n// Skill configurations\nexport interface SkillConfig {\n name: string\n title: string\n description: string\n skillDir: string\n rulesDir: string\n metadataFile: string\n outputFile: string\n sectionMap: Record\n}\n\nexport const SKILLS: Record = {\n 'react-best-practices': {\n name: 'react-best-practices',\n title: 'React Best Practices',\n description: 'React and Next.js codebases',\n skillDir: join(SKILLS_DIR, 'react-best-practices'),\n rulesDir: join(SKILLS_DIR, 'react-best-practices/rules'),\n metadataFile: join(SKILLS_DIR, 'react-best-practices/metadata.json'),\n outputFile: join(SKILLS_DIR, 'react-best-practices/AGENTS.md'),\n sectionMap: {\n async: 1,\n bundle: 2,\n server: 3,\n client: 4,\n rerender: 5,\n rendering: 6,\n js: 7,\n advanced: 8,\n },\n },\n 'react-native-skills': {\n name: 'react-native-skills',\n title: 'React Native Skills',\n description: 'React Native codebases',\n skillDir: join(SKILLS_DIR, 'react-native-skills'),\n rulesDir: join(SKILLS_DIR, 'react-native-skills/rules'),\n metadataFile: join(SKILLS_DIR, 'react-native-skills/metadata.json'),\n outputFile: join(SKILLS_DIR, 'react-native-skills/AGENTS.md'),\n sectionMap: {\n rendering: 1,\n 'list-performance': 2,\n animation: 3,\n scroll: 4,\n navigation: 5,\n 'react-state': 6,\n state: 7,\n 'react-compiler': 8,\n ui: 9,\n 'design-system': 10,\n monorepo: 11,\n imports: 12,\n js: 13,\n fonts: 14,\n },\n },\n 'composition-patterns': {\n name: 'composition-patterns',\n title: 'React Composition Patterns',\n description: 'React codebases using composition',\n skillDir: join(SKILLS_DIR, 'composition-patterns'),\n rulesDir: join(SKILLS_DIR, 'composition-patterns/rules'),\n metadataFile: join(SKILLS_DIR, 'composition-patterns/metadata.json'),\n outputFile: join(SKILLS_DIR, 'composition-patterns/AGENTS.md'),\n sectionMap: {\n architecture: 1,\n state: 2,\n patterns: 3,\n react19: 4,\n },\n },\n}\n\n// Default skill (for backwards compatibility)\nexport const DEFAULT_SKILL = 'react-best-practices'\n\n// Legacy exports for backwards compatibility\nexport const SKILL_DIR = SKILLS[DEFAULT_SKILL].skillDir\nexport const RULES_DIR = SKILLS[DEFAULT_SKILL].rulesDir\nexport const METADATA_FILE = SKILLS[DEFAULT_SKILL].metadataFile\nexport const OUTPUT_FILE = SKILLS[DEFAULT_SKILL].outputFile\n\n// Test cases are build artifacts, not part of the skill\nexport const TEST_CASES_FILE = join(BUILD_DIR, 'test-cases.json')\n" }, { "path": "packages/react-best-practices-build/src/extract-tests.ts", "content": "#!/usr/bin/env node\n/**\n * Extract test cases from rules for LLM evaluation\n */\n\nimport { readdir, writeFile } from 'fs/promises'\nimport { join } from 'path'\nimport { Rule, TestCase } from './types.js'\nimport { parseRuleFile } from './parser.js'\nimport { RULES_DIR, TEST_CASES_FILE } from './config.js'\n\n/**\n * Extract test cases from a rule\n */\nfunction extractTestCases(rule: Rule): TestCase[] {\n const testCases: TestCase[] = []\n \n rule.examples.forEach((example, index) => {\n const isBad = example.label.toLowerCase().includes('incorrect') || \n example.label.toLowerCase().includes('wrong') ||\n example.label.toLowerCase().includes('bad')\n const isGood = example.label.toLowerCase().includes('correct') ||\n example.label.toLowerCase().includes('good')\n \n if (isBad || isGood) {\n testCases.push({\n ruleId: rule.id,\n ruleTitle: rule.title,\n type: isBad ? 'bad' : 'good',\n code: example.code,\n language: example.language || 'typescript',\n description: example.description || `${example.label} example for ${rule.title}`\n })\n }\n })\n \n return testCases\n}\n\n/**\n * Main extraction function\n */\nasync function extractTests() {\n try {\n console.log('Extracting test cases from rules...')\n console.log(`Rules directory: ${RULES_DIR}`)\n console.log(`Output file: ${TEST_CASES_FILE}`)\n \n const files = await readdir(RULES_DIR)\n const ruleFiles = files.filter(f => f.endsWith('.md') && !f.startsWith('_') && f !== 'README.md')\n \n const allTestCases: TestCase[] = []\n \n for (const file of ruleFiles) {\n const filePath = join(RULES_DIR, file)\n try {\n const { rule } = await parseRuleFile(filePath)\n const testCases = extractTestCases(rule)\n allTestCases.push(...testCases)\n } catch (error) {\n console.error(`Error processing ${file}:`, error)\n }\n }\n \n // Write test cases as JSON\n await writeFile(TEST_CASES_FILE, JSON.stringify(allTestCases, null, 2), 'utf-8')\n \n console.log(`✓ Extracted ${allTestCases.length} test cases to ${TEST_CASES_FILE}`)\n console.log(` - Bad examples: ${allTestCases.filter(tc => tc.type === 'bad').length}`)\n console.log(` - Good examples: ${allTestCases.filter(tc => tc.type === 'good').length}`)\n } catch (error) {\n console.error('Extraction failed:', error)\n process.exit(1)\n }\n}\n\nextractTests()\n" }, { "path": "packages/react-best-practices-build/src/migrate.ts", "content": "#!/usr/bin/env node\n/**\n * Migration script to split RPG.md into individual rule files\n * This is a one-time script to help migrate existing content\n */\n\nimport { readFile, writeFile, mkdir } from 'fs/promises'\nimport { join } from 'path'\nimport { existsSync } from 'fs'\nimport { SKILL_DIR, RULES_DIR } from './config.js'\n\nconst RPG_FILE = join(SKILL_DIR, 'RPG.md')\n\n/**\n * Extract section number and title from heading\n */\nfunction parseSectionHeading(line: string): { number: number; title: string } | null {\n const match = line.match(/^##\\s+(\\d+)\\.\\s+(.+)$/)\n if (match) {\n return {\n number: parseInt(match[1]),\n title: match[2].trim()\n }\n }\n return null\n}\n\n/**\n * Extract rule number and title from heading\n */\nfunction parseRuleHeading(line: string): { section: number; subsection: number; title: string } | null {\n const match = line.match(/^###\\s+(\\d+)\\.(\\d+)\\s+(.+)$/)\n if (match) {\n return {\n section: parseInt(match[1]),\n subsection: parseInt(match[2]),\n title: match[3].trim()\n }\n }\n return null\n}\n\n/**\n * Extract impact from line\n */\nfunction extractImpact(line: string): { impact: string; description?: string } | null {\n const match = line.match(/\\*\\*Impact:\\s*(\\w+(?:-\\w+)?)\\s*(?:\\(([^)]+)\\))?/i)\n if (match) {\n return {\n impact: match[1].toUpperCase().replace(/-/g, '-'),\n description: match[2]\n }\n }\n return null\n}\n\nasync function migrate() {\n try {\n console.log('Migrating RPG.md to individual rule files...')\n \n if (!existsSync(RPG_FILE)) {\n console.error(`RPG.md not found at ${RPG_FILE}`)\n process.exit(1)\n }\n \n // Ensure rules directory exists\n if (!existsSync(RULES_DIR)) {\n await mkdir(RULES_DIR, { recursive: true })\n }\n \n const content = await readFile(RPG_FILE, 'utf-8')\n const lines = content.split('\\n')\n \n let currentSection: { number: number; title: string; impact?: string; introduction?: string } | null = null\n let currentRule: { section: number; subsection: number; title: string; content: string[] } | null = null\n let inCodeBlock = false\n \n for (let i = 0; i < lines.length; i++) {\n const line = lines[i]\n \n // Check for section heading\n const sectionInfo = parseSectionHeading(line)\n if (sectionInfo) {\n // Save previous section if exists\n if (currentSection) {\n const sectionFile = join(RULES_DIR, `section-${currentSection.number}.md`)\n let sectionContent = `# ${currentSection.number}. ${currentSection.title}\\n\\n`\n if (currentSection.impact) {\n sectionContent += `**Impact: ${currentSection.impact}**\\n\\n`\n }\n if (currentSection.introduction) {\n sectionContent += `## Introduction\\n\\n${currentSection.introduction}\\n`\n }\n await writeFile(sectionFile, sectionContent, 'utf-8')\n }\n \n currentSection = sectionInfo\n currentRule = null\n \n // Look for impact on next few lines\n for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {\n const impactInfo = extractImpact(lines[j])\n if (impactInfo) {\n currentSection.impact = impactInfo.impact\n break\n }\n }\n \n // Collect introduction text until first rule\n let introduction: string[] = []\n for (let j = i + 1; j < lines.length; j++) {\n if (parseRuleHeading(lines[j])) {\n break\n }\n if (!lines[j].match(/^###/)) {\n introduction.push(lines[j])\n }\n }\n currentSection.introduction = introduction.join('\\n').trim()\n continue\n }\n \n // Check for rule heading\n const ruleInfo = parseRuleHeading(line)\n if (ruleInfo) {\n // Save previous rule if exists\n if (currentRule && currentSection) {\n const ruleFile = join(RULES_DIR, `section-${currentRule.section}-rule-${currentRule.subsection}.md`)\n const ruleContent = currentRule.content.join('\\n')\n await writeFile(ruleFile, ruleContent, 'utf-8')\n console.log(`Created ${ruleFile}`)\n }\n \n currentRule = {\n ...ruleInfo,\n content: [line]\n }\n continue\n }\n \n // Accumulate content for current rule\n if (currentRule) {\n currentRule.content.push(line)\n }\n }\n \n // Save last rule\n if (currentRule && currentSection) {\n const ruleFile = join(RULES_DIR, `section-${currentRule.section}-rule-${currentRule.subsection}.md`)\n const ruleContent = currentRule.content.join('\\n')\n await writeFile(ruleFile, ruleContent, 'utf-8')\n console.log(`Created ${ruleFile}`)\n }\n \n // Save last section\n if (currentSection) {\n const sectionFile = join(RULES_DIR, `section-${currentSection.number}.md`)\n let sectionContent = `# ${currentSection.number}. ${currentSection.title}\\n\\n`\n if (currentSection.impact) {\n sectionContent += `**Impact: ${currentSection.impact}**\\n\\n`\n }\n if (currentSection.introduction) {\n sectionContent += `## Introduction\\n\\n${currentSection.introduction}\\n`\n }\n await writeFile(sectionFile, sectionContent, 'utf-8')\n console.log(`Created ${sectionFile}`)\n }\n \n console.log('\\n✓ Migration complete!')\n console.log('Note: You may need to manually add frontmatter to rule files.')\n } catch (error) {\n console.error('Migration failed:', error)\n process.exit(1)\n }\n}\n\nmigrate()\n" }, { "path": "packages/react-best-practices-build/src/parser.ts", "content": "/**\n * Parser for rule markdown files\n */\n\nimport { readFile } from 'fs/promises'\nimport { basename } from 'path'\nimport { Rule, ImpactLevel } from './types.js'\n\nexport interface RuleFile {\n section: number\n subsection?: number\n rule: Rule\n}\n\n/**\n * Parse a rule markdown file into a Rule object\n */\nexport async function parseRuleFile(\n filePath: string,\n sectionMap?: Record\n): Promise {\n const rawContent = await readFile(filePath, 'utf-8')\n // Normalize Windows CRLF line endings to LF for consistent parsing\n const content = rawContent.replace(/\\r\\n/g, '\\n')\n const lines = content.split('\\n')\n\n // Extract frontmatter if present\n let frontmatter: Record = {}\n let contentStart = 0\n\n if (content.startsWith('---')) {\n const frontmatterEnd = content.indexOf('---', 3)\n if (frontmatterEnd !== -1) {\n const frontmatterText = content.slice(3, frontmatterEnd).trim()\n frontmatterText.split('\\n').forEach((line) => {\n const [key, ...valueParts] = line.split(':')\n if (key && valueParts.length) {\n const value = valueParts.join(':').trim()\n frontmatter[key.trim()] = value.replace(/^[\"']|[\"']$/g, '')\n }\n })\n contentStart = frontmatterEnd + 3\n }\n }\n\n // Parse the rule content\n const ruleContent = content.slice(contentStart).trim()\n const ruleLines = ruleContent.split('\\n')\n\n // Extract title (first # or ## heading)\n let title = ''\n let titleLine = 0\n for (let i = 0; i < ruleLines.length; i++) {\n if (ruleLines[i].startsWith('##')) {\n title = ruleLines[i].replace(/^##+\\s*/, '').trim()\n titleLine = i\n break\n }\n }\n\n // Extract impact\n let impact: Rule['impact'] = 'MEDIUM'\n let impactDescription = ''\n let explanation = ''\n let examples: Rule['examples'] = []\n let references: string[] = []\n\n // Parse content after title\n let currentExample: {\n label: string\n description?: string\n code: string\n language?: string\n additionalText?: string\n } | null = null\n let inCodeBlock = false\n let codeBlockLanguage = 'typescript'\n let codeBlockContent: string[] = []\n let afterCodeBlock = false\n let additionalText: string[] = []\n let hasCodeBlockForCurrentExample = false\n\n for (let i = titleLine + 1; i < ruleLines.length; i++) {\n const line = ruleLines[i]\n\n // Impact line\n if (line.includes('**Impact:')) {\n const match = line.match(\n /\\*\\*Impact:\\s*(\\w+(?:-\\w+)?)\\s*(?:\\(([^)]+)\\))?/i\n )\n if (match) {\n impact = match[1].toUpperCase().replace(/-/g, '-') as ImpactLevel\n impactDescription = match[2] || ''\n }\n continue\n }\n\n // Code block start\n if (line.startsWith('```')) {\n if (inCodeBlock) {\n // End of code block\n if (currentExample) {\n currentExample.code = codeBlockContent.join('\\n')\n currentExample.language = codeBlockLanguage\n }\n codeBlockContent = []\n inCodeBlock = false\n afterCodeBlock = true\n } else {\n // Start of code block\n inCodeBlock = true\n hasCodeBlockForCurrentExample = true\n codeBlockLanguage = line.slice(3).trim() || 'typescript'\n codeBlockContent = []\n afterCodeBlock = false\n }\n continue\n }\n\n if (inCodeBlock) {\n codeBlockContent.push(line)\n continue\n }\n\n // Example label (Incorrect, Correct, Example, Usage, Implementation, etc.)\n // Match pattern: **Label:** or **Label (description):** at end of line\n // This distinguishes example labels from inline bold text like \"**Trade-off:** some text\"\n const labelMatch = line.match(/^\\*\\*([^:]+?):\\*?\\*?$/)\n if (labelMatch) {\n // Save previous example if it exists\n if (currentExample) {\n if (additionalText.length > 0) {\n currentExample.additionalText = additionalText.join('\\n\\n')\n additionalText = []\n }\n examples.push(currentExample)\n }\n afterCodeBlock = false\n hasCodeBlockForCurrentExample = false\n\n const fullLabel = labelMatch[1].trim()\n // Try to extract description from parentheses if present (handles simple cases)\n // For nested parentheses like \"Incorrect (O(n) per lookup)\", we keep the full label\n const descMatch = fullLabel.match(\n /^([A-Za-z]+(?:\\s+[A-Za-z]+)*)\\s*\\(([^()]+)\\)$/\n )\n currentExample = {\n label: descMatch ? descMatch[1].trim() : fullLabel,\n description: descMatch ? descMatch[2].trim() : undefined,\n code: '',\n language: codeBlockLanguage,\n }\n continue\n }\n\n // Reference links\n if (line.startsWith('Reference:') || line.startsWith('References:')) {\n // Save current example before processing references\n if (currentExample) {\n if (additionalText.length > 0) {\n currentExample.additionalText = additionalText.join('\\n\\n')\n additionalText = []\n }\n examples.push(currentExample)\n currentExample = null\n }\n\n const refMatch = line.match(/\\[([^\\]]+)\\]\\(([^)]+)\\)/g)\n if (refMatch) {\n references.push(\n ...refMatch.map((ref) => {\n const m = ref.match(/\\[([^\\]]+)\\]\\(([^)]+)\\)/)\n return m ? m[2] : ref\n })\n )\n }\n continue\n }\n\n // Regular text (explanation or additional context after examples)\n if (line.trim() && !line.startsWith('#')) {\n if (!currentExample && !inCodeBlock) {\n // Main explanation before any examples\n explanation += (explanation ? '\\n\\n' : '') + line\n } else if (\n currentExample &&\n (afterCodeBlock || !hasCodeBlockForCurrentExample)\n ) {\n // Text after a code block, or text in a section without a code block\n // (e.g., \"When NOT to use this pattern:\" with bullet points instead of code)\n additionalText.push(line)\n }\n }\n }\n\n // Handle last example if still open\n if (currentExample) {\n if (additionalText.length > 0) {\n currentExample.additionalText = additionalText.join('\\n\\n')\n }\n examples.push(currentExample)\n }\n\n // Infer section from filename patterns\n // Pattern: area-description.md where area determines section\n const filename = basename(filePath)\n\n // Default section map (for backwards compatibility)\n const defaultSectionMap: Record = {\n async: 1,\n bundle: 2,\n server: 3,\n client: 4,\n rerender: 5,\n rendering: 6,\n js: 7,\n advanced: 8,\n }\n\n const effectiveSectionMap = sectionMap || defaultSectionMap\n\n // Extract area from filename - try longest prefix match first\n // This handles prefixes like \"list-performance\" vs \"list\"\n const filenameParts = filename.replace('.md', '').split('-')\n let section = 0\n\n // Try progressively shorter prefixes to find the best match\n for (let len = filenameParts.length; len > 0; len--) {\n const prefix = filenameParts.slice(0, len).join('-')\n if (effectiveSectionMap[prefix] !== undefined) {\n section = effectiveSectionMap[prefix]\n break\n }\n }\n\n // Fall back to frontmatter section if specified\n section = frontmatter.section || section || 0\n\n const rule: Rule = {\n id: '', // Will be assigned by build script based on sorted order\n title: frontmatter.title || title,\n section: section,\n subsection: undefined,\n impact: frontmatter.impact || impact,\n impactDescription: frontmatter.impactDescription || impactDescription,\n explanation: frontmatter.explanation || explanation.trim(),\n examples,\n references: frontmatter.references\n ? frontmatter.references.split(',').map((r: string) => r.trim())\n : references,\n tags: frontmatter.tags\n ? frontmatter.tags.split(',').map((t: string) => t.trim())\n : undefined,\n }\n\n return {\n section,\n subsection: 0,\n rule,\n }\n}\n" }, { "path": "packages/react-best-practices-build/src/types.ts", "content": "/**\n * Type definitions for React Performance Guidelines rules\n */\n\nexport type ImpactLevel = 'CRITICAL' | 'HIGH' | 'MEDIUM-HIGH' | 'MEDIUM' | 'LOW-MEDIUM' | 'LOW'\n\nexport interface CodeExample {\n label: string // e.g., \"Incorrect\", \"Correct\", \"Example\"\n description?: string // Optional description before code\n code: string\n language?: string // Default: 'typescript' or 'tsx'\n additionalText?: string // Optional text after code block (explanations, reasons)\n}\n\nexport interface Rule {\n id: string // e.g., \"1.1\", \"2.3\"\n title: string\n section: number // Main section number (1-8)\n subsection?: number // Subsection number within section\n impact: ImpactLevel\n impactDescription?: string // e.g., \"2-10× improvement\"\n explanation: string\n examples: CodeExample[]\n references?: string[] // URLs or citations\n tags?: string[] // For categorization/search\n}\n\nexport interface Section {\n number: number\n title: string\n impact: ImpactLevel\n impactDescription?: string\n introduction?: string\n rules: Rule[]\n}\n\nexport interface GuidelinesDocument {\n version: string\n organization: string\n date: string\n abstract: string\n sections: Section[]\n references?: string[]\n}\n\nexport interface TestCase {\n ruleId: string\n ruleTitle: string\n type: 'bad' | 'good'\n code: string\n language: string\n description?: string\n}\n" }, { "path": "packages/react-best-practices-build/src/validate.ts", "content": "#!/usr/bin/env node\n/**\n * Validate rule files follow the correct structure\n */\n\nimport { readdir } from 'fs/promises'\nimport { join } from 'path'\nimport { Rule } from './types.js'\nimport { parseRuleFile } from './parser.js'\nimport { RULES_DIR } from './config.js'\n\ninterface ValidationError {\n file: string\n ruleId?: string\n message: string\n}\n\n/**\n * Validate a rule\n */\nfunction validateRule(rule: Rule, file: string): ValidationError[] {\n const errors: ValidationError[] = []\n \n // Note: rule.id is auto-generated during build, not required in source files\n \n if (!rule.title || rule.title.trim().length === 0) {\n errors.push({ file, ruleId: rule.id, message: 'Missing or empty title' })\n }\n \n if (!rule.explanation || rule.explanation.trim().length === 0) {\n errors.push({ file, ruleId: rule.id, message: 'Missing or empty explanation' })\n }\n \n if (!rule.examples || rule.examples.length === 0) {\n errors.push({ file, ruleId: rule.id, message: 'Missing examples (need at least one bad and one good example)' })\n } else {\n // Filter out informational examples (notes, trade-offs, etc.) that don't have code\n const codeExamples = rule.examples.filter(e => e.code && e.code.trim().length > 0)\n \n const hasBad = codeExamples.some(e => \n e.label.toLowerCase().includes('incorrect') || \n e.label.toLowerCase().includes('wrong') ||\n e.label.toLowerCase().includes('bad')\n )\n const hasGood = codeExamples.some(e => \n e.label.toLowerCase().includes('correct') || \n e.label.toLowerCase().includes('good') ||\n e.label.toLowerCase().includes('usage') ||\n e.label.toLowerCase().includes('implementation') ||\n e.label.toLowerCase().includes('example')\n )\n \n if (codeExamples.length === 0) {\n errors.push({ file, ruleId: rule.id, message: 'Missing code examples' })\n } else if (!hasBad && !hasGood) {\n errors.push({ file, ruleId: rule.id, message: 'Missing bad/incorrect or good/correct examples' })\n }\n }\n \n const validImpacts: Rule['impact'][] = ['CRITICAL', 'HIGH', 'MEDIUM-HIGH', 'MEDIUM', 'LOW-MEDIUM', 'LOW']\n if (!validImpacts.includes(rule.impact)) {\n errors.push({ file, ruleId: rule.id, message: `Invalid impact level: ${rule.impact}. Must be one of: ${validImpacts.join(', ')}` })\n }\n \n return errors\n}\n\n/**\n * Main validation function\n */\nasync function validate() {\n try {\n console.log('Validating rule files...')\n console.log(`Rules directory: ${RULES_DIR}`)\n \n const files = await readdir(RULES_DIR)\n const ruleFiles = files.filter(f => f.endsWith('.md') && !f.startsWith('_'))\n \n const allErrors: ValidationError[] = []\n \n for (const file of ruleFiles) {\n const filePath = join(RULES_DIR, file)\n try {\n const { rule } = await parseRuleFile(filePath)\n const errors = validateRule(rule, file)\n allErrors.push(...errors)\n } catch (error) {\n allErrors.push({ \n file, \n message: `Failed to parse: ${error instanceof Error ? error.message : String(error)}` \n })\n }\n }\n \n if (allErrors.length > 0) {\n console.error('\\n✗ Validation failed:\\n')\n allErrors.forEach(error => {\n console.error(` ${error.file}${error.ruleId ? ` (${error.ruleId})` : ''}: ${error.message}`)\n })\n process.exit(1)\n } else {\n console.log(`✓ All ${ruleFiles.length} rule files are valid`)\n }\n } catch (error) {\n console.error('Validation failed:', error)\n process.exit(1)\n }\n}\n\nvalidate()\n" }, { "path": "packages/react-best-practices-build/test-cases.json", "content": "[\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Store Event Handlers in Refs\",\n \"type\": \"bad\",\n \"code\": \"function useWindowEvent(event: string, handler: (e) => void) {\\n useEffect(() => {\\n window.addEventListener(event, handler)\\n return () => window.removeEventListener(event, handler)\\n }, [event, handler])\\n}\",\n \"language\": \"tsx\",\n \"description\": \"re-subscribes on every render\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Store Event Handlers in Refs\",\n \"type\": \"good\",\n \"code\": \"import { useEffectEvent } from 'react'\\n\\nfunction useWindowEvent(event: string, handler: (e) => void) {\\n const onEvent = useEffectEvent(handler)\\n\\n useEffect(() => {\\n window.addEventListener(event, onEvent)\\n return () => window.removeEventListener(event, onEvent)\\n }, [event])\\n}\",\n \"language\": \"tsx\",\n \"description\": \"stable subscription\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Initialize App Once, Not Per Mount\",\n \"type\": \"bad\",\n \"code\": \"function Comp() {\\n useEffect(() => {\\n loadFromStorage()\\n checkAuthToken()\\n }, [])\\n\\n // ...\\n}\",\n \"language\": \"tsx\",\n \"description\": \"runs twice in dev, re-runs on remount\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Initialize App Once, Not Per Mount\",\n \"type\": \"good\",\n \"code\": \"let didInit = false\\n\\nfunction Comp() {\\n useEffect(() => {\\n if (didInit) return\\n didInit = true\\n loadFromStorage()\\n checkAuthToken()\\n }, [])\\n\\n // ...\\n}\",\n \"language\": \"tsx\",\n \"description\": \"once per app load\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"useEffectEvent for Stable Callback Refs\",\n \"type\": \"bad\",\n \"code\": \"function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {\\n const [query, setQuery] = useState('')\\n\\n useEffect(() => {\\n const timeout = setTimeout(() => onSearch(query), 300)\\n return () => clearTimeout(timeout)\\n }, [query, onSearch])\\n}\",\n \"language\": \"tsx\",\n \"description\": \"effect re-runs on every callback change\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"useEffectEvent for Stable Callback Refs\",\n \"type\": \"good\",\n \"code\": \"import { useEffectEvent } from 'react';\\n\\nfunction SearchInput({ onSearch }: { onSearch: (q: string) => void }) {\\n const [query, setQuery] = useState('')\\n const onSearchEvent = useEffectEvent(onSearch)\\n\\n useEffect(() => {\\n const timeout = setTimeout(() => onSearchEvent(query), 300)\\n return () => clearTimeout(timeout)\\n }, [query])\\n}\",\n \"language\": \"tsx\",\n \"description\": \"using React's useEffectEvent\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Prevent Waterfall Chains in API Routes\",\n \"type\": \"bad\",\n \"code\": \"export async function GET(request: Request) {\\n const session = await auth()\\n const config = await fetchConfig()\\n const data = await fetchData(session.user.id)\\n return Response.json({ data, config })\\n}\",\n \"language\": \"typescript\",\n \"description\": \"config waits for auth, data waits for both\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Prevent Waterfall Chains in API Routes\",\n \"type\": \"good\",\n \"code\": \"export async function GET(request: Request) {\\n const sessionPromise = auth()\\n const configPromise = fetchConfig()\\n const session = await sessionPromise\\n const [config, data] = await Promise.all([\\n configPromise,\\n fetchData(session.user.id)\\n ])\\n return Response.json({ data, config })\\n}\",\n \"language\": \"typescript\",\n \"description\": \"auth and config start immediately\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Defer Await Until Needed\",\n \"type\": \"bad\",\n \"code\": \"async function handleRequest(userId: string, skipProcessing: boolean) {\\n const userData = await fetchUserData(userId)\\n \\n if (skipProcessing) {\\n // Returns immediately but still waited for userData\\n return { skipped: true }\\n }\\n \\n // Only this branch uses userData\\n return processUserData(userData)\\n}\",\n \"language\": \"typescript\",\n \"description\": \"blocks both branches\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Defer Await Until Needed\",\n \"type\": \"good\",\n \"code\": \"async function handleRequest(userId: string, skipProcessing: boolean) {\\n if (skipProcessing) {\\n // Returns immediately without waiting\\n return { skipped: true }\\n }\\n \\n // Fetch only when needed\\n const userData = await fetchUserData(userId)\\n return processUserData(userData)\\n}\",\n \"language\": \"typescript\",\n \"description\": \"only blocks when needed\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Dependency-Based Parallelization\",\n \"type\": \"bad\",\n \"code\": \"const [user, config] = await Promise.all([\\n fetchUser(),\\n fetchConfig()\\n])\\nconst profile = await fetchProfile(user.id)\",\n \"language\": \"typescript\",\n \"description\": \"profile waits for config unnecessarily\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Dependency-Based Parallelization\",\n \"type\": \"good\",\n \"code\": \"import { all } from 'better-all'\\n\\nconst { user, config, profile } = await all({\\n async user() { return fetchUser() },\\n async config() { return fetchConfig() },\\n async profile() {\\n return fetchProfile((await this.$.user).id)\\n }\\n})\",\n \"language\": \"typescript\",\n \"description\": \"config and profile run in parallel\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Promise.all() for Independent Operations\",\n \"type\": \"bad\",\n \"code\": \"const user = await fetchUser()\\nconst posts = await fetchPosts()\\nconst comments = await fetchComments()\",\n \"language\": \"typescript\",\n \"description\": \"sequential execution, 3 round trips\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Promise.all() for Independent Operations\",\n \"type\": \"good\",\n \"code\": \"const [user, posts, comments] = await Promise.all([\\n fetchUser(),\\n fetchPosts(),\\n fetchComments()\\n])\",\n \"language\": \"typescript\",\n \"description\": \"parallel execution, 1 round trip\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Strategic Suspense Boundaries\",\n \"type\": \"bad\",\n \"code\": \"async function Page() {\\n const data = await fetchData() // Blocks entire page\\n \\n return (\\n
\\n
Sidebar
\\n
Header
\\n
\\n \\n
\\n
Footer
\\n
\\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"wrapper blocked by data fetching\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Strategic Suspense Boundaries\",\n \"type\": \"good\",\n \"code\": \"function Page() {\\n return (\\n
\\n
Sidebar
\\n
Header
\\n
\\n }>\\n \\n \\n
\\n
Footer
\\n
\\n )\\n}\\n\\nasync function DataDisplay() {\\n const data = await fetchData() // Only blocks this component\\n return
{data.content}
\\n}\",\n \"language\": \"tsx\",\n \"description\": \"wrapper shows immediately, data streams in\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Avoid Barrel File Imports\",\n \"type\": \"bad\",\n \"code\": \"import { Check, X, Menu } from 'lucide-react'\\n// Loads 1,583 modules, takes ~2.8s extra in dev\\n// Runtime cost: 200-800ms on every cold start\\n\\nimport { Button, TextField } from '@mui/material'\\n// Loads 2,225 modules, takes ~4.2s extra in dev\",\n \"language\": \"tsx\",\n \"description\": \"imports entire library\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Avoid Barrel File Imports\",\n \"type\": \"good\",\n \"code\": \"import Check from 'lucide-react/dist/esm/icons/check'\\nimport X from 'lucide-react/dist/esm/icons/x'\\nimport Menu from 'lucide-react/dist/esm/icons/menu'\\n// Loads only 3 modules (~2KB vs ~1MB)\\n\\nimport Button from '@mui/material/Button'\\nimport TextField from '@mui/material/TextField'\\n// Loads only what you use\",\n \"language\": \"tsx\",\n \"description\": \"imports only what you need\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Defer Non-Critical Third-Party Libraries\",\n \"type\": \"bad\",\n \"code\": \"import { Analytics } from '@vercel/analytics/react'\\n\\nexport default function RootLayout({ children }) {\\n return (\\n \\n \\n {children}\\n \\n \\n \\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"blocks initial bundle\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Defer Non-Critical Third-Party Libraries\",\n \"type\": \"good\",\n \"code\": \"import dynamic from 'next/dynamic'\\n\\nconst Analytics = dynamic(\\n () => import('@vercel/analytics/react').then(m => m.Analytics),\\n { ssr: false }\\n)\\n\\nexport default function RootLayout({ children }) {\\n return (\\n \\n \\n {children}\\n \\n \\n \\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"loads after hydration\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Dynamic Imports for Heavy Components\",\n \"type\": \"bad\",\n \"code\": \"import { MonacoEditor } from './monaco-editor'\\n\\nfunction CodePanel({ code }: { code: string }) {\\n return \\n}\",\n \"language\": \"tsx\",\n \"description\": \"Monaco bundles with main chunk ~300KB\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Dynamic Imports for Heavy Components\",\n \"type\": \"good\",\n \"code\": \"import dynamic from 'next/dynamic'\\n\\nconst MonacoEditor = dynamic(\\n () => import('./monaco-editor').then(m => m.MonacoEditor),\\n { ssr: false }\\n)\\n\\nfunction CodePanel({ code }: { code: string }) {\\n return \\n}\",\n \"language\": \"tsx\",\n \"description\": \"Monaco loads on demand\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Deduplicate Global Event Listeners\",\n \"type\": \"bad\",\n \"code\": \"function useKeyboardShortcut(key: string, callback: () => void) {\\n useEffect(() => {\\n const handler = (e: KeyboardEvent) => {\\n if (e.metaKey && e.key === key) {\\n callback()\\n }\\n }\\n window.addEventListener('keydown', handler)\\n return () => window.removeEventListener('keydown', handler)\\n }, [key, callback])\\n}\",\n \"language\": \"tsx\",\n \"description\": \"N instances = N listeners\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Deduplicate Global Event Listeners\",\n \"type\": \"good\",\n \"code\": \"import useSWRSubscription from 'swr/subscription'\\n\\n// Module-level Map to track callbacks per key\\nconst keyCallbacks = new Map void>>()\\n\\nfunction useKeyboardShortcut(key: string, callback: () => void) {\\n // Register this callback in the Map\\n useEffect(() => {\\n if (!keyCallbacks.has(key)) {\\n keyCallbacks.set(key, new Set())\\n }\\n keyCallbacks.get(key)!.add(callback)\\n\\n return () => {\\n const set = keyCallbacks.get(key)\\n if (set) {\\n set.delete(callback)\\n if (set.size === 0) {\\n keyCallbacks.delete(key)\\n }\\n }\\n }\\n }, [key, callback])\\n\\n useSWRSubscription('global-keydown', () => {\\n const handler = (e: KeyboardEvent) => {\\n if (e.metaKey && keyCallbacks.has(e.key)) {\\n keyCallbacks.get(e.key)!.forEach(cb => cb())\\n }\\n }\\n window.addEventListener('keydown', handler)\\n return () => window.removeEventListener('keydown', handler)\\n })\\n}\\n\\nfunction Profile() {\\n // Multiple shortcuts will share the same listener\\n useKeyboardShortcut('p', () => { /* ... */ }) \\n useKeyboardShortcut('k', () => { /* ... */ })\\n // ...\\n}\",\n \"language\": \"tsx\",\n \"description\": \"N instances = 1 listener\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Version and Minimize localStorage Data\",\n \"type\": \"bad\",\n \"code\": \"// No version, stores everything, no error handling\\nlocalStorage.setItem('userConfig', JSON.stringify(fullUserObject))\\nconst data = localStorage.getItem('userConfig')\",\n \"language\": \"typescript\",\n \"description\": \"Incorrect example for Version and Minimize localStorage Data\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Version and Minimize localStorage Data\",\n \"type\": \"good\",\n \"code\": \"const VERSION = 'v2'\\n\\nfunction saveConfig(config: { theme: string; language: string }) {\\n try {\\n localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))\\n } catch {\\n // Throws in incognito/private browsing, quota exceeded, or disabled\\n }\\n}\\n\\nfunction loadConfig() {\\n try {\\n const data = localStorage.getItem(`userConfig:${VERSION}`)\\n return data ? JSON.parse(data) : null\\n } catch {\\n return null\\n }\\n}\\n\\n// Migration from v1 to v2\\nfunction migrate() {\\n try {\\n const v1 = localStorage.getItem('userConfig:v1')\\n if (v1) {\\n const old = JSON.parse(v1)\\n saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })\\n localStorage.removeItem('userConfig:v1')\\n }\\n } catch {}\\n}\",\n \"language\": \"typescript\",\n \"description\": \"Correct example for Version and Minimize localStorage Data\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use Passive Event Listeners for Scrolling Performance\",\n \"type\": \"bad\",\n \"code\": \"useEffect(() => {\\n const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)\\n const handleWheel = (e: WheelEvent) => console.log(e.deltaY)\\n \\n document.addEventListener('touchstart', handleTouch)\\n document.addEventListener('wheel', handleWheel)\\n \\n return () => {\\n document.removeEventListener('touchstart', handleTouch)\\n document.removeEventListener('wheel', handleWheel)\\n }\\n}, [])\",\n \"language\": \"typescript\",\n \"description\": \"Incorrect example for Use Passive Event Listeners for Scrolling Performance\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use Passive Event Listeners for Scrolling Performance\",\n \"type\": \"good\",\n \"code\": \"useEffect(() => {\\n const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)\\n const handleWheel = (e: WheelEvent) => console.log(e.deltaY)\\n \\n document.addEventListener('touchstart', handleTouch, { passive: true })\\n document.addEventListener('wheel', handleWheel, { passive: true })\\n \\n return () => {\\n document.removeEventListener('touchstart', handleTouch)\\n document.removeEventListener('wheel', handleWheel)\\n }\\n}, [])\",\n \"language\": \"typescript\",\n \"description\": \"Correct example for Use Passive Event Listeners for Scrolling Performance\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use SWR for Automatic Deduplication\",\n \"type\": \"bad\",\n \"code\": \"function UserList() {\\n const [users, setUsers] = useState([])\\n useEffect(() => {\\n fetch('/api/users')\\n .then(r => r.json())\\n .then(setUsers)\\n }, [])\\n}\",\n \"language\": \"tsx\",\n \"description\": \"no deduplication, each instance fetches\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use SWR for Automatic Deduplication\",\n \"type\": \"good\",\n \"code\": \"import useSWR from 'swr'\\n\\nfunction UserList() {\\n const { data: users } = useSWR('/api/users', fetcher)\\n}\",\n \"language\": \"tsx\",\n \"description\": \"multiple instances share one request\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Avoid Layout Thrashing\",\n \"type\": \"bad\",\n \"code\": \"function layoutThrashing(element: HTMLElement) {\\n element.style.width = '100px'\\n const width = element.offsetWidth // Forces reflow\\n element.style.height = '200px'\\n const height = element.offsetHeight // Forces another reflow\\n}\",\n \"language\": \"typescript\",\n \"description\": \"interleaved reads and writes force reflows\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Avoid Layout Thrashing\",\n \"type\": \"good\",\n \"code\": \"function updateElementStyles(element: HTMLElement) {\\n // Batch all writes together\\n element.style.width = '100px'\\n element.style.height = '200px'\\n element.style.backgroundColor = 'blue'\\n element.style.border = '1px solid black'\\n \\n // Read after all writes are done (single reflow)\\n const { width, height } = element.getBoundingClientRect()\\n}\",\n \"language\": \"typescript\",\n \"description\": \"batch writes, then read once\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Avoid Layout Thrashing\",\n \"type\": \"good\",\n \"code\": \"function updateElementStyles(element: HTMLElement) {\\n element.classList.add('highlighted-box')\\n \\n const { width, height } = element.getBoundingClientRect()\\n}\",\n \"language\": \"typescript\",\n \"description\": \"batch reads, then writes\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Cache Repeated Function Calls\",\n \"type\": \"bad\",\n \"code\": \"function ProjectList({ projects }: { projects: Project[] }) {\\n return (\\n
\\n {projects.map(project => {\\n // slugify() called 100+ times for same project names\\n const slug = slugify(project.name)\\n \\n return \\n })}\\n
\\n )\\n}\",\n \"language\": \"typescript\",\n \"description\": \"redundant computation\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Cache Repeated Function Calls\",\n \"type\": \"good\",\n \"code\": \"// Module-level cache\\nconst slugifyCache = new Map()\\n\\nfunction cachedSlugify(text: string): string {\\n if (slugifyCache.has(text)) {\\n return slugifyCache.get(text)!\\n }\\n const result = slugify(text)\\n slugifyCache.set(text, result)\\n return result\\n}\\n\\nfunction ProjectList({ projects }: { projects: Project[] }) {\\n return (\\n
\\n {projects.map(project => {\\n // Computed only once per unique project name\\n const slug = cachedSlugify(project.name)\\n \\n return \\n })}\\n
\\n )\\n}\",\n \"language\": \"typescript\",\n \"description\": \"cached results\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Cache Property Access in Loops\",\n \"type\": \"bad\",\n \"code\": \"for (let i = 0; i < arr.length; i++) {\\n process(obj.config.settings.value)\\n}\",\n \"language\": \"typescript\",\n \"description\": \"3 lookups × N iterations\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Cache Property Access in Loops\",\n \"type\": \"good\",\n \"code\": \"const value = obj.config.settings.value\\nconst len = arr.length\\nfor (let i = 0; i < len; i++) {\\n process(value)\\n}\",\n \"language\": \"typescript\",\n \"description\": \"1 lookup total\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Cache Storage API Calls\",\n \"type\": \"bad\",\n \"code\": \"function getTheme() {\\n return localStorage.getItem('theme') ?? 'light'\\n}\\n// Called 10 times = 10 storage reads\",\n \"language\": \"typescript\",\n \"description\": \"reads storage on every call\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Cache Storage API Calls\",\n \"type\": \"good\",\n \"code\": \"const storageCache = new Map()\\n\\nfunction getLocalStorage(key: string) {\\n if (!storageCache.has(key)) {\\n storageCache.set(key, localStorage.getItem(key))\\n }\\n return storageCache.get(key)\\n}\\n\\nfunction setLocalStorage(key: string, value: string) {\\n localStorage.setItem(key, value)\\n storageCache.set(key, value) // keep cache in sync\\n}\",\n \"language\": \"typescript\",\n \"description\": \"Map cache\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Combine Multiple Array Iterations\",\n \"type\": \"bad\",\n \"code\": \"const admins = users.filter(u => u.isAdmin)\\nconst testers = users.filter(u => u.isTester)\\nconst inactive = users.filter(u => !u.isActive)\",\n \"language\": \"typescript\",\n \"description\": \"3 iterations\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Combine Multiple Array Iterations\",\n \"type\": \"good\",\n \"code\": \"const admins: User[] = []\\nconst testers: User[] = []\\nconst inactive: User[] = []\\n\\nfor (const user of users) {\\n if (user.isAdmin) admins.push(user)\\n if (user.isTester) testers.push(user)\\n if (!user.isActive) inactive.push(user)\\n}\",\n \"language\": \"typescript\",\n \"description\": \"1 iteration\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Early Return from Functions\",\n \"type\": \"bad\",\n \"code\": \"function validateUsers(users: User[]) {\\n let hasError = false\\n let errorMessage = ''\\n \\n for (const user of users) {\\n if (!user.email) {\\n hasError = true\\n errorMessage = 'Email required'\\n }\\n if (!user.name) {\\n hasError = true\\n errorMessage = 'Name required'\\n }\\n // Continues checking all users even after error found\\n }\\n \\n return hasError ? { valid: false, error: errorMessage } : { valid: true }\\n}\",\n \"language\": \"typescript\",\n \"description\": \"processes all items even after finding answer\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Early Return from Functions\",\n \"type\": \"good\",\n \"code\": \"function validateUsers(users: User[]) {\\n for (const user of users) {\\n if (!user.email) {\\n return { valid: false, error: 'Email required' }\\n }\\n if (!user.name) {\\n return { valid: false, error: 'Name required' }\\n }\\n }\\n\\n return { valid: true }\\n}\",\n \"language\": \"typescript\",\n \"description\": \"returns immediately on first error\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use flatMap to Map and Filter in One Pass\",\n \"type\": \"bad\",\n \"code\": \"const userNames = users\\n .map(user => user.isActive ? user.name : null)\\n .filter(Boolean)\",\n \"language\": \"typescript\",\n \"description\": \"2 iterations, intermediate array\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use flatMap to Map and Filter in One Pass\",\n \"type\": \"good\",\n \"code\": \"const userNames = users.flatMap(user =>\\n user.isActive ? [user.name] : []\\n)\",\n \"language\": \"typescript\",\n \"description\": \"1 iteration, no intermediate array\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Hoist RegExp Creation\",\n \"type\": \"bad\",\n \"code\": \"function Highlighter({ text, query }: Props) {\\n const regex = new RegExp(`(${query})`, 'gi')\\n const parts = text.split(regex)\\n return <>{parts.map((part, i) => ...)}\\n}\",\n \"language\": \"tsx\",\n \"description\": \"new RegExp every render\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Hoist RegExp Creation\",\n \"type\": \"good\",\n \"code\": \"const EMAIL_REGEX = /^[^\\\\s@]+@[^\\\\s@]+\\\\.[^\\\\s@]+$/\\n\\nfunction Highlighter({ text, query }: Props) {\\n const regex = useMemo(\\n () => new RegExp(`(${escapeRegex(query)})`, 'gi'),\\n [query]\\n )\\n const parts = text.split(regex)\\n return <>{parts.map((part, i) => ...)}\\n}\",\n \"language\": \"tsx\",\n \"description\": \"memoize or hoist\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Build Index Maps for Repeated Lookups\",\n \"type\": \"bad\",\n \"code\": \"function processOrders(orders: Order[], users: User[]) {\\n return orders.map(order => ({\\n ...order,\\n user: users.find(u => u.id === order.userId)\\n }))\\n}\",\n \"language\": \"typescript\",\n \"description\": \"Incorrect (O(n) per lookup) example for Build Index Maps for Repeated Lookups\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Build Index Maps for Repeated Lookups\",\n \"type\": \"good\",\n \"code\": \"function processOrders(orders: Order[], users: User[]) {\\n const userById = new Map(users.map(u => [u.id, u]))\\n\\n return orders.map(order => ({\\n ...order,\\n user: userById.get(order.userId)\\n }))\\n}\",\n \"language\": \"typescript\",\n \"description\": \"Correct (O(1) per lookup) example for Build Index Maps for Repeated Lookups\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Early Length Check for Array Comparisons\",\n \"type\": \"bad\",\n \"code\": \"function hasChanges(current: string[], original: string[]) {\\n // Always sorts and joins, even when lengths differ\\n return current.sort().join() !== original.sort().join()\\n}\",\n \"language\": \"typescript\",\n \"description\": \"always runs expensive comparison\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Early Length Check for Array Comparisons\",\n \"type\": \"good\",\n \"code\": \"function hasChanges(current: string[], original: string[]) {\\n // Early return if lengths differ\\n if (current.length !== original.length) {\\n return true\\n }\\n // Only sort when lengths match\\n const currentSorted = current.toSorted()\\n const originalSorted = original.toSorted()\\n for (let i = 0; i < currentSorted.length; i++) {\\n if (currentSorted[i] !== originalSorted[i]) {\\n return true\\n }\\n }\\n return false\\n}\",\n \"language\": \"typescript\",\n \"description\": \"Correct (O(1) length check first) example for Early Length Check for Array Comparisons\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use Loop for Min/Max Instead of Sort\",\n \"type\": \"bad\",\n \"code\": \"interface Project {\\n id: string\\n name: string\\n updatedAt: number\\n}\\n\\nfunction getLatestProject(projects: Project[]) {\\n const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)\\n return sorted[0]\\n}\",\n \"language\": \"typescript\",\n \"description\": \"Incorrect (O(n log n) - sort to find latest) example for Use Loop for Min/Max Instead of Sort\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use Loop for Min/Max Instead of Sort\",\n \"type\": \"bad\",\n \"code\": \"function getOldestAndNewest(projects: Project[]) {\\n const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)\\n return { oldest: sorted[0], newest: sorted[sorted.length - 1] }\\n}\",\n \"language\": \"typescript\",\n \"description\": \"Incorrect (O(n log n) - sort for oldest and newest) example for Use Loop for Min/Max Instead of Sort\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use Loop for Min/Max Instead of Sort\",\n \"type\": \"good\",\n \"code\": \"function getLatestProject(projects: Project[]) {\\n if (projects.length === 0) return null\\n \\n let latest = projects[0]\\n \\n for (let i = 1; i < projects.length; i++) {\\n if (projects[i].updatedAt > latest.updatedAt) {\\n latest = projects[i]\\n }\\n }\\n \\n return latest\\n}\\n\\nfunction getOldestAndNewest(projects: Project[]) {\\n if (projects.length === 0) return { oldest: null, newest: null }\\n \\n let oldest = projects[0]\\n let newest = projects[0]\\n \\n for (let i = 1; i < projects.length; i++) {\\n if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]\\n if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]\\n }\\n \\n return { oldest, newest }\\n}\",\n \"language\": \"typescript\",\n \"description\": \"Correct (O(n) - single loop) example for Use Loop for Min/Max Instead of Sort\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use Set/Map for O(1) Lookups\",\n \"type\": \"bad\",\n \"code\": \"const allowedIds = ['a', 'b', 'c', ...]\\nitems.filter(item => allowedIds.includes(item.id))\",\n \"language\": \"typescript\",\n \"description\": \"Incorrect (O(n) per check) example for Use Set/Map for O(1) Lookups\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use Set/Map for O(1) Lookups\",\n \"type\": \"good\",\n \"code\": \"const allowedIds = new Set(['a', 'b', 'c', ...])\\nitems.filter(item => allowedIds.has(item.id))\",\n \"language\": \"typescript\",\n \"description\": \"Correct (O(1) per check) example for Use Set/Map for O(1) Lookups\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use toSorted() Instead of sort() for Immutability\",\n \"type\": \"bad\",\n \"code\": \"function UserList({ users }: { users: User[] }) {\\n // Mutates the users prop array!\\n const sorted = useMemo(\\n () => users.sort((a, b) => a.name.localeCompare(b.name)),\\n [users]\\n )\\n return
{sorted.map(renderUser)}
\\n}\",\n \"language\": \"typescript\",\n \"description\": \"mutates original array\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use toSorted() Instead of sort() for Immutability\",\n \"type\": \"good\",\n \"code\": \"function UserList({ users }: { users: User[] }) {\\n // Creates new sorted array, original unchanged\\n const sorted = useMemo(\\n () => users.toSorted((a, b) => a.name.localeCompare(b.name)),\\n [users]\\n )\\n return
{sorted.map(renderUser)}
\\n}\",\n \"language\": \"typescript\",\n \"description\": \"creates new array\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Animate SVG Wrapper Instead of SVG Element\",\n \"type\": \"bad\",\n \"code\": \"function LoadingSpinner() {\\n return (\\n \\n \\n \\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"animating SVG directly - no hardware acceleration\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Animate SVG Wrapper Instead of SVG Element\",\n \"type\": \"good\",\n \"code\": \"function LoadingSpinner() {\\n return (\\n
\\n \\n \\n \\n
\\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"animating wrapper div - hardware accelerated\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use Explicit Conditional Rendering\",\n \"type\": \"bad\",\n \"code\": \"function Badge({ count }: { count: number }) {\\n return (\\n
\\n {count && {count}}\\n
\\n )\\n}\\n\\n// When count = 0, renders:
0
\\n// When count = 5, renders:
5
\",\n \"language\": \"tsx\",\n \"description\": \"renders \\\"0\\\" when count is 0\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use Explicit Conditional Rendering\",\n \"type\": \"good\",\n \"code\": \"function Badge({ count }: { count: number }) {\\n return (\\n
\\n {count > 0 ? {count} : null}\\n
\\n )\\n}\\n\\n// When count = 0, renders:
\\n// When count = 5, renders:
5
\",\n \"language\": \"tsx\",\n \"description\": \"renders nothing when count is 0\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Hoist Static JSX Elements\",\n \"type\": \"bad\",\n \"code\": \"function LoadingSkeleton() {\\n return
\\n}\\n\\nfunction Container() {\\n return (\\n
\\n {loading && }\\n
\\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"recreates element every render\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Hoist Static JSX Elements\",\n \"type\": \"good\",\n \"code\": \"const loadingSkeleton = (\\n
\\n)\\n\\nfunction Container() {\\n return (\\n
\\n {loading && loadingSkeleton}\\n
\\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"reuses same element\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Prevent Hydration Mismatch Without Flickering\",\n \"type\": \"bad\",\n \"code\": \"function ThemeWrapper({ children }: { children: ReactNode }) {\\n // localStorage is not available on server - throws error\\n const theme = localStorage.getItem('theme') || 'light'\\n \\n return (\\n
\\n {children}\\n
\\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"breaks SSR\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Prevent Hydration Mismatch Without Flickering\",\n \"type\": \"bad\",\n \"code\": \"function ThemeWrapper({ children }: { children: ReactNode }) {\\n const [theme, setTheme] = useState('light')\\n \\n useEffect(() => {\\n // Runs after hydration - causes visible flash\\n const stored = localStorage.getItem('theme')\\n if (stored) {\\n setTheme(stored)\\n }\\n }, [])\\n \\n return (\\n
\\n {children}\\n
\\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"visual flickering\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Prevent Hydration Mismatch Without Flickering\",\n \"type\": \"good\",\n \"code\": \"function ThemeWrapper({ children }: { children: ReactNode }) {\\n return (\\n <>\\n
\\n {children}\\n
\\n \\n \\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"no flicker, no hydration mismatch\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Suppress Expected Hydration Mismatches\",\n \"type\": \"bad\",\n \"code\": \"function Timestamp() {\\n return {new Date().toLocaleString()}\\n}\",\n \"language\": \"tsx\",\n \"description\": \"known mismatch warnings\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Suppress Expected Hydration Mismatches\",\n \"type\": \"good\",\n \"code\": \"function Timestamp() {\\n return (\\n \\n {new Date().toLocaleString()}\\n \\n )\\n}\",\n \"language\": \"tsx\",\n \"description\": \"suppress expected mismatch only\"\n },\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Use defer or async on Script Tags\",\n \"type\": \"bad\",\n \"code\": \"export default function Document() {\\n return (\\n \\n \\n