or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build.mdcode-quality.mddocumentation.mdindex.mdmonorepo.mdrelease.mdtesting.mdutilities.md
tile.json

code-quality.mddocs/

Code Quality Tools

Aegir provides integrated code quality tools including ESLint-based linting, spell checking with cspell, dependency validation, and package.json structure validation.

Capabilities

Linting

ESLint-based code linting with TypeScript support and automatic fixing capabilities.

aegir lint [options]

Options:
  --fix             Automatically fix linting errors where possible (default: false)
  --files           Specific files to lint (array, default: ['src', 'test'])
  --silent          Disable eslint output (default: false)

Lint Configuration

Linting behavior can be configured via .aegir.js or package.json:

interface LintOptions {
  /** Automatically fix errors if possible */
  fix: boolean;
  /** Files to lint */
  files: string[];
  /** Disable eslint output */
  silent: boolean;
}

Usage Examples:

# Basic linting
aegir lint

# Auto-fix issues
aegir lint --fix

# Lint specific files
aegir lint --files src/utils.js --files test/

# Silent mode
aegir lint --silent

Configuration:

// .aegir.js
module.exports = {
  lint: {
    fix: true,
    files: ['src', 'test', 'scripts'],
    silent: false
  }
};

ESLint Configuration

Aegir provides a pre-configured ESLint setup accessible as a shareable config:

// Available as: aegir/eslint.config.js
// Pre-configured with:
// - TypeScript support (@typescript-eslint/parser)
// - Modern JavaScript standards (neostandard)
// - Import validation (eslint-plugin-import)
// - JSDoc validation (eslint-plugin-jsdoc)  
// - Test-specific rules (eslint-plugin-no-only-tests)
// - Unix-style formatting (eslint-formatter-unix)

Usage in project:

// eslint.config.js
import aegirConfig from 'aegir/eslint.config.js';

export default [
  ...aegirConfig,
  // Your custom overrides
  {
    rules: {
      'no-console': 'warn'
    }
  }
];

Spell Checking

Integrated spell checking using cspell with project-specific dictionaries.

aegir spell-check

# Spell checks:
# - Source code comments and strings
# - Documentation files
# - README and markdown files
# - Uses project's cspell.json configuration
# - Includes custom dictionaries from dictionaries/ folder

Configuration Files:

// cspell.json (automatically used)
{
  "version": "0.2",
  "language": "en",
  "words": ["aegir", "monorepo", "webworker"],
  "dictionaries": ["project-words"],
  "dictionaryDefinitions": [
    {
      "name": "project-words",
      "path": "./dictionaries/project-words.txt"
    }
  ],
  "ignorePaths": ["node_modules", "dist", "coverage"]
}

Dependency Checking

Validates project dependencies to detect unused dependencies and missing declarations.

aegir dependency-check [options]

# Also available as:
aegir dep-check
aegir dep

Options:
  --unused                     Throw error on unused dependencies (default: true)
  --ignore                     Dependencies to ignore when checking
  --productionIgnorePatterns   File patterns to ignore for production deps
  --developmentIgnorePatterns  File patterns to ignore for dev deps

Dependency Check Configuration

interface DependencyCheckOptions {
  /** Throw error on unused dependencies */
  unused: boolean;
  /** Ignore these dependencies when checking */
  ignore: string[];
  /** Files to ignore when checking production dependencies */
  productionIgnorePatterns: string[];
  /** Files to ignore when checking dev dependencies */
  developmentIgnorePatterns: string[];
}

Usage Examples:

# Check all dependencies
aegir dep-check

# Allow unused dependencies
aegir dep-check --no-unused

# Ignore specific packages
aegir dep-check --ignore typescript --ignore @types/node

Configuration:

// .aegir.js
module.exports = {
  dependencyCheck: {
    unused: true,
    ignore: [
      'typescript',      // May be used in build process
      '@types/node',     // Type definitions
      'aegir'            // Self-reference in monorepos
    ],
    productionIgnorePatterns: [
      'test/**/*',       // Test files don't affect production deps
      'scripts/**/*'     // Build scripts
    ],
    developmentIgnorePatterns: [
      'src/**/*'         // Source code doesn't use dev deps
    ]
  }
};

Package.json Validation

Validates package.json structure and content according to npm and Aegir best practices.

aegir lint-package-json

# Also available as:
aegir lint-package
aegir lpj

# Validates:
# - Required fields (name, version, main, files, scripts)
# - Proper script definitions for Aegir workflows
# - File array includes necessary paths
# - Repository and bug tracking URLs
# - License field compliance
# - Proper export/import field configurations

Expected package.json structure:

{
  "name": "my-package",
  "version": "1.0.0",
  "main": "src/index.js",
  "files": ["src", "dist"],
  "scripts": {
    "lint": "aegir lint",
    "build": "aegir build", 
    "test": "aegir test",
    "release": "aegir release"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/user/repo.git"
  },
  "license": "MIT"
}

Project Structure Validation

Comprehensive project structure and configuration validation.

aegir check-project

# Validates:
# - Required directories exist (src/, test/)
# - Entry point files are present
# - Build configuration is valid
# - Test files follow naming conventions
# - TypeScript configuration (if present)
# - Git repository setup

General Health Check

Comprehensive project health check that validates build outputs, analyzes bundle dependencies and checks for Node.js built-in module usage.

aegir check

# Performs:
# - Bundle analysis and dependency validation
# - Node.js built-in modules usage detection
# - Build output verification
# - Bundle size analysis via esbuild metafile
# - Checks for proper browser/Node.js compatibility

Health Check Features:

The check command performs build analysis by:

  1. Bundle Analysis: Uses esbuild to create a production bundle and analyze dependencies
  2. Built-in Detection: Scans for Node.js built-in modules (util, fs, path, crypto, etc.)
  3. Compatibility Check: Identifies potential browser compatibility issues
  4. Size Analysis: Generates bundle size statistics and dependency breakdown
  5. Output Validation: Verifies that build outputs are properly generated

Usage Examples:

# Run comprehensive project check
aegir check

# Often used in CI/CD pipelines before releases
npm run build
aegir check
npm run test

Document Code Validation

Validates TypeScript code examples in documentation files.

aegir document-check [options]
# Also available as:
aegir doc-check

Options:
  --inputFiles      Markdown files to verify (default: ['README.md'])
  --tsConfigPath    Alternative tsconfig.json path

Document Check Configuration

interface DocsVerifierOptions {
  /** Markdown files to be verified */
  inputFiles?: string[];
  /** Alternative tsconfig.json path */
  tsConfigPath?: string;
}

Usage Examples:

# Check README.md
aegir doc-check

# Check multiple files
aegir doc-check --inputFiles README.md --inputFiles docs/api.md

# Use custom TypeScript config
aegir doc-check --tsConfigPath tsconfig.docs.json

Configuration:

// .aegir.js
module.exports = {
  documentCheck: {
    inputFiles: ['README.md', 'docs/*.md'],
    tsConfigPath: './tsconfig.docs.json'
  }
};

Integration with CI/CD

Code quality tools integrate seamlessly with continuous integration:

# GitHub Actions example
- name: Install dependencies
  run: npm ci

- name: Lint code
  run: npm run lint

- name: Check dependencies  
  run: npx aegir dep-check

- name: Spell check
  run: npx aegir spell-check

- name: Validate package.json
  run: npx aegir lint-package-json

- name: Check project structure
  run: npx aegir check-project

Quality Gate Configuration

Configure quality gates by combining multiple checks:

# package.json scripts
{
  "scripts": {
    "lint": "aegir lint",
    "lint:fix": "aegir lint --fix",
    "quality": "npm run lint && aegir dep-check && aegir spell-check",
    "pretest": "npm run quality",
    "prerelease": "npm run quality && aegir check"
  }
}

### Project Maintenance

Project cleanup and maintenance utilities for removing build artifacts and temporary files.

```bash { .api }
aegir clean [files..]

# Removes build artifacts (default: dist folder)
# Can specify custom files/directories to remove

Usage Examples:

# Remove default build artifacts (dist folder)
aegir clean

# Remove specific files/directories
aegir clean dist build temp

# Remove multiple patterns
aegir clean "*.log" "tmp/*" dist

The clean command uses glob patterns and removes files safely using the rimraf library. By default, it removes the dist directory where build outputs are stored.