/quality-commands

title: Code Quality Commands
icon: check-double

Code Quality Commands

:::info This document covers all code quality commands for the eIsland project — ESLint, Stylelint, HTML validation, comment checks, and i18n completeness. :::

All commands are run from the project root:

npm run <script>

:::warning Commands using `--experimental-strip-types` require **Node.js 22+**. See [Frontend Setup — Prerequisites](/developer/environment-setup/frontend-setup.md#prerequisites). :::

ESLint

`lint`

Runs ESLint on the entire project with zero warnings allowed.

npm run lint

**Under the hood:** `eslint . --max-warnings=0`

**What it checks:**

• JavaScript / TypeScript syntax and best practices
• React hooks rules and JSX conventions
• Import ordering and deduplication
• JSDoc comment completeness
• Tailwind CSS class ordering and validity
• Accessibility (jsx-a11y)
• Promise handling patterns

:::important Run this before every commit. CI rejects PRs that fail the lint check. :::

`lint:eslint`

Alias for `lint` — runs the same ESLint check.

npm run lint:eslint

`lint:fix`

Runs ESLint with automatic fixing. Corrects formatting, import order, and other auto-fixable issues.

npm run lint:fix

**Under the hood:** `eslint . --fix --max-warnings=0`

:::tip Use `lint:fix` after pulling upstream changes to auto-resolve formatting conflicts. Review the diff before committing — auto-fix may change behavior in edge cases. :::

`lint:report`

Runs ESLint and generates an HTML report in `reports/eslint.html`. Useful for reviewing all violations in a browser with clickable file links.

npm run lint:report

**Under the hood:** `eslint . --max-warnings=0 --format html --output-file reports/eslint.html`

:::tip Use `lint:report` when onboarding or after a large refactor — the HTML report makes it easier to triage many violations than terminal output. :::

`lint:report:json`

Runs ESLint and generates a machine-readable JSON report in `reports/eslint.json`. Useful for CI pipelines or custom tooling that consumes lint results programmatically.

npm run lint:report:json

**Under the hood:** `eslint . --max-warnings=0 --format json --output-file reports/eslint.json`

`lint:comments`

Runs only the comment-related ESLint rules (JSDoc, file headers, method comments). Faster than a full lint when you only need to validate documentation compliance.

npm run lint:comments

**Under the hood:** `eslint . --config scripts/lint/comments.config.mjs --max-warnings=0`

**What it checks:**

• Copyright headers and `@file` / `@description` / `@author` tags
• JSDoc on exported functions, classes, and class methods
• Parameter and return value documentation

:::note This uses a dedicated config (`comments.config.mjs`) that filters the main ESLint config to only JSDoc and project comment rules. :::

Stylelint

`lint:css`

Runs Stylelint on all CSS and SCSS files in `src/` and `web/`.

npm run lint:css

**Under the hood:** `stylelint "{src,web}/**/*.{css,scss}" "web/**/.vuepress/**/*.{css,scss}" --max-warnings=0`

**What it checks:**

• Selector complexity limits (max classes, IDs, combinators)
• Property declaration order (position → display → box model → typography → visual)
• Color rules (no named colors, lowercase hex, angle units for hue)
• `!important` forbidden
• Kebab-case naming for classes, IDs, keyframes
• SCSS nesting, operator spacing, and mixin conventions

`lint:css:fix`

Runs Stylelint with automatic fixing.

npm run lint:css:fix

:::tip Stylelint auto-fix handles property reordering, shorthand consolidation, and quote normalization. Always review the output — property order changes can affect cascade behavior. :::

HTML Validation

`lint:html`

Validates all HTML files against the project's HTML standards.

npm run lint:html

**Under the hood:** `html-validate "{src,web}/**/*.html" --max-warnings=0`

**What it checks:**

• Lowercase `<!doctype html>` declaration
• Required `lang` attribute on `<html>`
• Required `alt` on `<img>` tags
• Double quotes for attributes
• Boolean attributes use omit style (e.g., `checked` not `checked="checked"`)
• Void elements omit self-closing slash
• Heading hierarchy (no skipped levels)
• Input elements have associated labels

:::note The project includes a custom `eisland/document-standards` HTML rule that enforces additional conventions beyond the standard `html-validate:recommended` preset. :::

Combined Commands

`lint:all`

Runs all lint checks in parallel — ESLint, Stylelint, HTML validation, and i18n completeness.

npm run lint:all

**Under the hood:** `run-p --continue-on-error lint:eslint lint:css lint:html i18n:check`

:::important `lint:all` uses `--continue-on-error`, so all checks run even if one fails. Review all failures, not just the first one. :::

`lint:config:test`

Runs the ESLint configuration self-test — validates that rules load correctly, environment isolation works, and key requirements are enforced.

npm run lint:config:test

**Under the hood:** `node --test scripts/lint/config.test.mjs`

**What it verifies:**

• Basic rules detect `var`, loose equality, `any`, and dangerous constructors
• Type-aware checks catch dangling promises
• Project rules detect shorthand order violations and bad filenames
• Comment rules enforce file headers, author tags, and JSDoc
• Disable comments require rule names and descriptions
• React rules detect hook violations, props spreading, and missing `alt`
• Node / browser global isolation works correctly
• CSS rules detect `!important`, named colors, and ID selectors
• HTML rules detect uppercase doctype, missing lang, and missing alt

:::tip Run `lint:config:test` after modifying any ESLint, Stylelint, or HTML-validate configuration to verify the changes don't break existing rules. :::

Comment & i18n Checks

`comment: