npm package: @oee-intellisuite/code-tester
Description: A comprehensive CLI tool for enforcing best practices across Node.js, .NET, and Python projects
Latest version: 1.0.0

# 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](#overview)
- [Features & Checks](#features--checks)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [Usage](#usage)
- [Project Types](#project-types)
- [Configuration](#configuration)
- [Available Checks](#available-checks)
- [OpenTelemetry](#opentelemetry)
- [Development](#development)
- [Contributing](#contributing)
- [License](#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)

```bash
npm install -g best-practices-cli
```

### Local Installation

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

## Quick Start

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

```bash
# 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](./docs/QUICK_REFERENCE.md)** - Essential commands and options at a glance
- **[Usage Guide](./docs/USAGE_GUIDE.md)** - Detailed usage examples and workflows
- **[Examples](./docs/EXAMPLES.md)** - Real-world project examples and integrations

## Usage

### Basic Commands

```bash
# 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`:

```bash
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:

```bash
best-practices init
```

### Example Configuration

```json
{
  "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

```bash
# 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:

```sh
# 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:

```bash
# 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.