OEE Code Tester CLI

A comprehensive CLI tool for enforcing best practices across Node.js, .NET, and Python projects. This tool helps maintain code quality, consistency, and adherence to industry standards across different technology stacks.

Table of Contents

• Overview
• Features & Checks
• Installation
• Quick Start
• Documentation
• Usage
• Project Types
• Configuration
• Available Checks
• OpenTelemetry
• Development
• Contributing
• License

Overview

OEE Code Tester CLI is a best-practices and compliance tool for Node.js, Python, and .NET projects. It validates project structure, configuration, code quality, and security using a set of automated checks. Now includes modular OpenTelemetry initialization for tracing, metrics, and logging.

Features & Checks

• Node.js:
  • package.json validation (required/recommended fields)
  • Node.js version check
  • TypeScript config (tsconfig.json)
  • ESLint config and linting
  • Prettier config and formatting
  • .gitignore validation
  • README.md existence
  • Dependency validation
  • VS Code settings
  • Malicious package detection
  • Import/dependency mismatch
• Python:
  • pyproject.toml validation
  • Virtualenv presence/activation check
  • Python version check
  • requirements.txt and dependency file validation
  • Python package version validation
  • Malicious dependency/source detection
  • Import/dependency mismatch
  • Type annotations and mypy config validation
  • Code formatting (Black)
  • Import sorting (isort)
  • Linting (ruff/flake8)
  • Security audit (pip-audit/safety)
  • VS Code settings
  • .gitignore validation
  • README.md existence
• .NET:
  • .csproj and project structure validation
  • .sln file validation
  • .editorconfig validation
  • .gitignore validation
  • README.md existence
  • Dependency injection pattern validation
  • Async/await usage pattern validation
  • Nullable reference types configuration
  • Error handling pattern validation
  • VS Code settings
  • .NET SDK version check
  • Vulnerable NuGet package scan

Installation

Global Installation (Recommended)

npm install -g best-practices-cli

Local Installation

npm install --save-dev best-practices-cli

Quick Start

Get started with the Best Practices CLI in just a few steps:

# 1. Install the CLI globally
npm install -g best-practices-cli

# 2. Navigate to your project
cd my-project

# 3. Initialize configuration
best-practices init

# 4. Run checks
best-practices check

# 5. Auto-fix issues
best-practices check --fix

Documentation

📚 Comprehensive Documentation Available:

• Quick Reference - Essential commands and options at a glance
• Usage Guide - Detailed usage examples and workflows
• Examples - Real-world project examples and integrations

Usage

Basic Commands

# Show help
best-practices --help

# Get project information
best-practices info

# List all available checks
best-practices list

# Initialize configuration for current project
best-practices init

# Run checks on current project
best-practices check

# Run checks with auto-fix
best-practices check --fix

# Run checks with verbose output
best-practices check --verbose

# Specify project type explicitly
best-practices check --type nodejs

# Use custom configuration file
best-practices check --config ./my-config.json

# Dry run (show what would be fixed without making changes)
best-practices check --fix --dry-run

Command Aliases

You can also use the shorter alias bp:

bp check --fix
bp info
bp list

Project Types

Node.js Projects

Detected by presence of:

• package.json
• node_modules/
• .js, .ts, .jsx, .tsx files
• tsconfig.json
• package-lock.json, yarn.lock, pnpm-lock.yaml

.NET Projects

Detected by presence of:

• .sln files
• .csproj, .vbproj, .fsproj files
• .cs files
• bin/, obj/ directories

Python Projects

Detected by presence of:

• pyproject.toml
• requirements.txt
• .py files
• setup.py
• Virtual environment directories (venv/, .venv/)

Configuration

The tool uses a .best-practices.json configuration file in your project root. Generate one with:

best-practices init

Example Configuration

{
  "version": "1.0.0",
  "projectType": "nodejs",
  "enabledChecks": {
    "check-package-json": true,
    "check-tsconfig": true,
    "check-eslint": true,
    "check-prettier": true,
    "check-gitignore": true,
    "check-readme": true,
    "check-dependencies": true,
    "check-vscode-settings": true
  },
  "customRules": {
    "requiredDependencies": ["@tanstack/react-query", "typescript"]
  },
  "paths": {
    "exclude": ["node_modules", "dist", "build"],
    "include": ["**/*"]
  }
}

Available Checks

Node.js Checks

| Check | Description | Auto-fixable | | ---------------------------- | ---------------------------------------------------- | ------------ | | check-package-json | Validates package.json structure and required fields | ❌ | | check-node-version | Validates installed Node.js version | ❌ | | check-tsconfig | Validates TypeScript configuration | ✅ | | check-eslint | Validates ESLint configuration and runs linting | ✅ | | check-prettier | Validates Prettier configuration and formatting | ✅ | | check-gitignore | Validates .gitignore file for Node.js projects | ✅ | | check-readme | Checks for README.md file existence | ❌ | | check-dependencies | Validates required dependencies are installed | ❌ | | check-vscode-settings | Validates VS Code settings configuration | ✅ | | check-malicious-packages | Security check for known malicious or suspicious packages | ✅ | | check-import-mismatch | Validates imports used in code match declared dependencies | ✅ |

Python Checks

| Check | Description | Auto-fixable | | ---------------------------- | ---------------------------------------------------------------- | ------------ | | check-pyproject-toml | Validates pyproject.toml configuration | ✅ | | check-virtualenv | Checks for a Python virtual environment (present/active) | ✅ | | check-python-version | Validates the installed Python interpreter version | ❌ | | check-requirements | Validates requirements.txt or dependency files | ❌ | | check-package-versions | Validates installed Python package versions against config rules | ❌ | | check-malicious-deps | Heuristic scan of requirements for suspicious or non-PyPI sources | ❌ | | check-dep-import-mismatch | Ensures imports in codebase match packages listed in requirements/pyproject | ❌ | | check-type-annotations | Validates type annotations and mypy configuration | ❌ | | check-code-formatting | Validates code formatting with black | ✅ | | check-import-sorting | Validates import sorting with isort | ✅ | | check-linting | Validates code quality with ruff/flake8 | ✅ | | check-security | Validates security with pip-audit/safety | ❌ | | check-vscode-settings | Validates VS Code settings for Python development | ✅ | | check-gitignore | Validates .gitignore file for Python projects | ✅ | | check-readme | Checks for README.md file existence | ✅ |

.NET Checks

| Check | Description | Auto-fixable | | ---------------------------- | ---------------------------------------------------------------- | ------------ | | check-project-files | Validates .csproj and project structure | ✅ | | check-solution-file | Validates .sln file structure | ✅ | | check-editorconfig | Validates .editorconfig for .NET projects | ✅ | | check-gitignore | Validates .gitignore file for .NET projects | ✅ | | check-readme | Checks for README.md file existence | ❌ | | check-dependency-injection | Validates proper dependency injection patterns | ❌ | | check-async-patterns | Validates async/await usage patterns | ❌ | | check-nullable-types | Validates nullable reference types configuration | ✅ | | check-error-handling | Validates error handling patterns | ❌ | | check-vscode-settings | Validates VS Code settings for .NET development | ✅ | | check-dotnet-version | Validates the installed .NET SDK version | ❌ | | check-vulnerable-packages | Scans for known vulnerable NuGet packages | ❌ |

OpenTelemetry

• Tracing, metrics, and logging are initialized automatically in the CLI (no data collection by default).
• Modular setup in src/otel/ for easy extension.

Development

Prerequisites

• Node.js 16.0.0 or higher
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/ooeintellisuite/oee-code-tester.git
cd oee-code-tester

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev -- check --help

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint and format code
npm run lint:fix
npm run format

Development Commands

Run these in the project root:

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests (unit & integration)
npm test

# Lint code
npm run lint

# Run the CLI in development
npm start -- <cli-args>
# Example:
npm start -- check --fix

Project Structure

src/
├── cli.ts                 # Main CLI entry point
├── core/                  # Core functionality
│   ├── cli-core.ts       # Main CLI orchestrator
│   ├── config-manager.ts # Configuration management
│   └── project-detector.ts # Project type detection
├── handlers/              # Project type handlers
│   ├── base-handler.ts   # Base handler interface
│   ├── nodejs-handler.ts # Node.js specific checks
│   ├── dotnet-handler.ts # .NET specific checks
│   └── python-handler.ts # Python specific checks
├── otel/                  # OpenTelemetry modules (tracing, metrics, logging)
├── types/                 # TypeScript type definitions
│   └── project-types.ts
└── utils/                 # Utility functions
    ├── dependencyUtils.ts
    ├── esLintUtils.ts
    ├── fileUtils.ts
    ├── gitignoreUtils.ts
    ├── prettierUtils.ts
    └── tsConfigUtils.ts
tests/                     # Test suite
test-projects/             # Sample projects for compliance testing

Adding New Checks

1. Add the check definition to the appropriate handler
2. Implement the check method
3. Add the check to the switch statement in runChecks
4. Update the configuration defaults
5. Add tests for the new check

Testing

The project uses Vitest for testing:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- src/handlers/nodejs-handler.test.ts

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b features/my-feature
3. Make your changes following the coding standards
4. Add tests for new functionality
5. Ensure all tests pass: npm test
6. Commit using conventional commits: git commit -m "feat: add new check"
7. Push to your fork: git push origin features/my-feature
8. Create a Pull Request

Coding Standards

• Use TypeScript with strict mode enabled
• Follow conventional commit messages
• Maintain test coverage above 80%
• Use Prettier for code formatting
• Use ESLint for code quality
• Functions should be under 50 lines
• Use descriptive variable and function names
• Add JSDoc comments for public APIs

License

See LICENSE file for details.