everforest-resources/.serena/memories/code-style-conventions.md

Code Style & Conventions - Everforest Resources

JavaScript/Node.js Style

Module System

• ES Modules: All files use .mjs extension
• Imports: Use ES6 import/export syntax
• Type: "type": "module" in package.json

Biome Configuration

The project uses Biome 2.x for linting and formatting with these settings:

• Version: 2.2.3 (latest)
• Indent: 2 spaces
• Line width: 100 characters
• Quotes: Single quotes for JavaScript, double for JSX
• Semicolons: Always required
• Trailing commas: ES5 style
• Arrow parentheses: As needed

Class Structure

class EverforestGenerator {
  constructor() {
    this.palette = null;
  }

  async methodName() {
    // Async/await preferred over Promises
  }
}

Naming Conventions

• Classes: PascalCase (EverforestGenerator)
• Methods: camelCase (loadPalette, processTemplate)
• Constants: camelCase for most, UPPER_SNAKE_CASE for true constants
• Files: kebab-case (generate-themes.mjs)

Error Handling

• Use try-catch blocks for async operations
• Log errors with emoji prefixes: console.error('❌ Failed to load palette')
• Exit with code 1 on critical errors: process.exit(1)

Console Output

• Use emoji for visual feedback:
  • ✅ Success messages
  • ❌ Error messages
  • 🎨 Starting operations
  • 📝 Progress updates
  • ✨ Completion messages

Code Quality Rules

• Variables: Use const by default, let when reassignment needed
• Functions: Prefer arrow functions for callbacks
• Imports: Organize imports automatically with Biome
• Unused Variables: Not allowed (error level)
• Block Statements: Always use braces for control structures
• forEach: Allowed for side effects (useIterableCallbackReturn disabled)

Template System Conventions

Placeholder Format

• Use double curly braces: {{colorName}}
• Available placeholders: {{bg}}, {{fg}}, {{red}}, {{orange}}, {{yellow}}, {{green}}, {{aqua}}, {{blue}}, {{purple}}, {{gray1}}, {{gray2}}, {{gray3}}

Template Files

• Named template.txt in each tool directory
• Multiple templates for complex tools (e.g., colors-template.txt, prompt-template.txt)
• Never edit generated output files directly

Documentation Style

Code Comments

• Use JSDoc-style comments for classes and methods
• Include purpose and architecture notes at file top
• Explain complex logic inline

Markdown

• Critical Rule: Use indented code blocks only (4 spaces)
• Never use triple backticks (```)
• Use emoji in headers and lists for visual hierarchy

Git Conventions

Commit Messages

• Follow Conventional Commits format
• Examples:
  • feat: add starship theme generator
  • fix: correct color mapping in templates
  • docs: update CLI installation guide

Branch Strategy

• Main branch: main
• All CI checks must pass for merge
• Required checks: lint + build + snapshots + commitlint + cli-verify

File Organization

Directory Structure

palettes/           # Color definitions (JSON/YAML)
scripts/            # Generator and validation scripts
cli/               # CLI tool templates and configs
editors/           # Editor theme files
terminals/         # Terminal configurations
web/               # CSS and demo files
docs/              # Documentation
meta/              # Project specifications
biome.json         # Biome 2.x configuration

File Naming

• Scripts: kebab-case.mjs
• Configs: Tool-specific conventions
• Templates: template.txt or tool-template.txt

Biome File Processing

Biome processes these files:

• JavaScript modules: scripts/**/*.mjs, scripts/**/*.js
• JSON files: *.json
• Root level JS files: *.mjs, *.js

Biome ignores:

• Generated output files
• Node modules and build artifacts
• Unknown file types (by default)

Development Commands

# Format code
npm run format           # Format all files with Biome 2.x

# Lint code
npm run lint            # Check for issues
npm run lint:fix        # Auto-fix issues

# Before committing
npm run lint:fix && npm run format