Ultracite Code Standards

This project uses Ultracite, a zero-config preset that enforces strict code quality standards through automated formatting and linting.

Quick Reference

• Format code: bunx ultracite fix
• Check for issues: bunx ultracite check
• Diagnose setup: bunx ultracite doctor

Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.

Core Principles

Write code that is accessible, performant, type-safe, and maintainable. Focus on clarity and explicit intent over brevity.

Type Safety & Explicitness

• Use explicit types for function parameters and return values when they enhance clarity
• Prefer unknown over any when the type is genuinely unknown
• Use const assertions (as const) for immutable values and literal types
• Leverage TypeScript's type narrowing instead of type assertions
• Use meaningful variable names instead of magic numbers - extract constants with descriptive names

Modern JavaScript/TypeScript

• Use arrow functions for callbacks and short functions
• Prefer for...of loops over .forEach() and indexed for loops
• Use optional chaining (?.) and nullish coalescing (??) for safer property access
• Prefer template literals over string concatenation
• Use destructuring for object and array assignments
• Use const by default, let only when reassignment is needed, never var

Async & Promises

• Always await promises in async functions - don't forget to use the return value
• Use async/await syntax instead of promise chains for better readability
• Handle errors appropriately in async code with try-catch blocks
• Don't use async functions as Promise executors

React & JSX

• Use function components over class components
• Call hooks at the top level only, never conditionally
• Specify all dependencies in hook dependency arrays correctly
• Use the key prop for elements in iterables (prefer unique IDs over array indices)
• Nest children between opening and closing tags instead of passing as props
• Don't define components inside other components
• Use semantic HTML and ARIA attributes for accessibility:
  • Provide meaningful alt text for images
  • Use proper heading hierarchy
  • Add labels for form inputs
  • Include keyboard event handlers alongside mouse events
  • Use semantic elements (<button>, <nav>, etc.) instead of divs with roles

Error Handling & Debugging

• Remove console.log, debugger, and alert statements from production code
• Throw Error objects with descriptive messages, not strings or other values
• Use try-catch blocks meaningfully - don't catch errors just to rethrow them
• Prefer early returns over nested conditionals for error cases

Code Organization

• Keep functions focused and under reasonable cognitive complexity limits
• Extract complex conditions into well-named boolean variables
• Use early returns to reduce nesting
• Prefer simple conditionals over nested ternary operators
• Group related code together and separate concerns
• Avoid import cycles; move shared code into a module both sides import

Security

• Add rel="noopener noreferrer" when using target="_blank" on links
• Avoid dangerouslySetInnerHTML unless absolutely necessary
• Don't use eval() or assign directly to document.cookie
• Validate and sanitize user input

Performance

• Avoid spread syntax in accumulators within loops
• Use top-level regex literals instead of creating them in loops
• Prefer specific imports over namespace imports
• Avoid barrel files (index files that re-export everything)
• Use proper image components (e.g., Next.js <Image>) over <img> tags

Framework-Specific Guidance

Next.js:

• Use Next.js <Image> component for images
• Use next/head or App Router metadata API for head elements
• Use Server Components for async data fetching instead of async Client Components

React 19+:

• Use ref as a prop instead of React.forwardRef

Solid/Svelte/Vue/Qwik:

• Use class and for attributes (not className or htmlFor)

Testing

• Write assertions inside it() or test() blocks
• Avoid done callbacks in async tests - use async/await instead
• Don't use .only or .skip in committed code
• Keep test suites reasonably flat - avoid excessive describe nesting

When Oxlint + Oxfmt Can't Help

Oxlint + Oxfmt will catch most mechanical issues automatically. Focus your attention on:

1. Business logic correctness - Oxlint + Oxfmt can't validate your algorithms
2. Meaningful naming - Use descriptive names for functions, variables, and types
3. Architecture decisions - Component structure, data flow, and API design
4. Edge cases - Handle boundary conditions and error states
5. User experience - Accessibility, performance, and usability considerations
6. Documentation - Add comments for complex logic, but prefer self-documenting code

Most formatting and common issues are automatically fixed by Oxlint + Oxfmt. Run bunx ultracite fix before committing to ensure compliance.

Architecture

Package layout

.
├── packages/
│   ├── core/                        PRIVATE    the diagnostic engine, consumed as raw TS ("main": src/index.ts)
│   │   └── src/
│   │       ├── types/               shared cross-package TS types (DockerfileInstruction, Diagnostic, ProjectInfo, …)
│   │       ├── project-info/        project discovery (discoverProject)
│   │       ├── config/              configuration loader (loadConfig)
│   │       ├── parsers/             Dockerfile and Compose parsers
│   │       ├── rules/               rule definitions (Security, Performance, Best Practices, Compose, Image Size)
│   │       ├── runners/             rule orchestration; resolveSeverity applies the configured severity
│   │       ├── schemas/             hand-rolled config validator (validateConfig)
│   │       ├── errors/              ConfigError, ParseError, FileNotFoundError (plain Error subclasses)
│   │       ├── report.ts            report assembly
│   │       └── scoring.ts           SCORE_BUCKETS, getScoreBucket, calculateScore
│   ├── docker-doctor/               PUBLISHED  the CLI, @docker-doctor/cli, bundled by tsdown
│   │   └── src/
│   │       ├── cli.ts               flag parsing, scan orchestration, exit codes
│   │       ├── agents/              skill install, handoff payload, agent launching, clipboard
│   │       ├── formatters/          terminal.ts, the human-readable report
│   │       └── workflow-scaffold.ts writes .github/workflows/docker-doctor.yml
│   └── videos/                      PRIVATE    Remotion release videos
├── apps/
│   └── web/                         PRIVATE    Next.js + fumadocs site (app/, components/, content/, lib/, scripts/)
├── kits/
│   └── docker-doctor/               PRIVATE    Docker Sandboxes kit (spec v3); docker-doctor.yaml is synced by `bun run kit:sync`
├── skills/                          docker-doctor (bundled into the npm package), docker-author, improve-docker
├── scripts/                         generate-rules-doc.ts + rule-page-content.ts, sync-kit-spec.ts, render-github-action-comment.mjs
└── action.yml                       composite GitHub Action

Conventions worth knowing

• Rules and parsers are plain synchronous functions: packages/core/src/rules/ and packages/core/src/parsers/ return values directly. No async, no generators, no wrapper types. Keep them that way.
• Diagnostics come from one factory: every rule builds its findings with packages/core/src/rules/create-diagnostic.ts. The runners in packages/core/src/runners/ then apply the configured severity.
• Rule docs pages are generated: author the prose in scripts/rule-page-content.ts, then run bun run docs:rules. Generation fails when a rule has no authored entry, and the Format CI job diffs the output.
• Two artifacts are copied at release time: skills/docker-doctor is copied into the npm package at build, and the version and CLI pin in kits/docker-doctor/docker-doctor.yaml are synced by bun run kit:sync.
• User-visible CLI changes need a changeset: that includes edits to the bundled skill, since it ships inside @docker-doctor/cli.