tessl/npm-aegir

JavaScript project management tool with opinionated build, test, and release workflows

—

Pending

Overview

Eval results

Files

Code Quality Tools

Name: tessl/npm-aegir
Author: tessl

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:

Bundle Analysis: Uses esbuild to create a production bundle and analyze dependencies
Built-in Detection: Scans for Node.js built-in modules (util, fs, path, crypto, etc.)
Compatibility Check: Identifies potential browser compatibility issues
Size Analysis: Generates bundle size statistics and dependency breakdown
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.

Install with Tessl CLI