nitp-build-tools/README.md

Official build system for NIT Patna's backend services - A powerful Maven-based build automation tool with cross-platform support

# @nitp/build-tools

[![npm version](https://badge.fury.io/js/%40nitp%2Fbuild-tools.svg)](https://badge.fury.io/js/%40nitp%2Fbuild-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js CI](https://github.com/ashishkr375/adminportal_updated_new/workflows/Node.js%20CI/badge.svg)](https://github.com/ashishkr375/adminportal_updated_new/actions)

**Official build system for NIT Patna's backend services** - A powerful, cross-platform Maven-based build automation tool with advanced features for testing, quality assurance, and deployment.

## 👨‍💻 Developer

**Created by: [Ashish Kumar](https://github.com/ashishkr375)**

- 🔗 **GitHub**: [https://github.com/ashishkr375](https://github.com/ashishkr375)
- 💼 **LinkedIn**: [https://www.linkedin.com/in/ashish-kumar-nitp/](https://www.linkedin.com/in/ashish-kumar-nitp/)
- 🏫 **Institution**: NIT Patna
- 🌟 **Project**: Backend Services Build System

---

## 📋 Table of Contents

- [Features](#-features)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Requirements](#-requirements)
- [Commands](#-commands)
- [Configuration](#-configuration)
- [Environments](#-environments)
- [Code Coverage](#-code-coverage)
- [Quality Standards](#-quality-standards)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

## ✨ Features

- 🚀 **Cross-Platform Support**: Works seamlessly on Windows, macOS, and Linux
- 🔧 **Maven Integration**: Full Maven lifecycle management with advanced configurations
- 📊 **Code Coverage**: Integrated JaCoCo coverage reporting with configurable thresholds
- 🧪 **Testing Framework**: Support for unit and integration tests with JUnit 5
- 🔍 **Quality Assurance**: Built-in Spotless, CheckStyle, PMD, and SpotBugs integration
- 🌍 **Multi-Environment**: Support for dev, test, and production environments
- 📈 **Progress Tracking**: Real-time build progress and detailed logging
- 🎨 **Beautiful CLI**: Colored output with progress indicators and ASCII art
- 🏥 **Health Checks**: Built-in system diagnostics and requirements validation
- ⚙️ **Configurable**: Highly customizable through JSON configuration files

## 📦 Installation

### Global Installation (Recommended)

```bash
npm install -g @nitp/build-tools
```

### Project-Specific Installation

```bash
npm install --save-dev @nitp/build-tools
```

### Verify Installation

```bash
nitp-build --version
nitp-build doctor    # Check system health
```

## 🚀 Quick Start

```bash
# Show all available commands
nitp-build --help

# Check system requirements
nitp-build doctor

# Show system information
nitp-build info

# Build the project
nitp-build build

# Run tests with coverage
nitp-build test

# Start development server
nitp-build start:admin --env=dev
```

## 📋 Requirements

### System Requirements

- **Node.js**: >= 14.0.0
- **npm**: >= 6.0.0
- **Java**: >= 17 (OpenJDK or Oracle JDK)
- **Maven**: >= 3.8.0
- **Git**: Latest version

### Platform Support

| Platform | Status | Notes |
|----------|--------|-------|
| Windows  | ✅ Full Support | Tested on Windows 10/11 |
| macOS    | ✅ Full Support | Tested on macOS 11+ |
| Linux    | ✅ Full Support | Tested on Ubuntu, CentOS, Debian |

## 🔧 Commands

### Build Commands

```bash
# Full build with tests and quality checks
nitp-build build

# Quick build without tests (for development)
nitp-build build:fast

# Build with specific environment
nitp-build build --env=prod --verbose
```

### Testing Commands

```bash
# Run all tests with coverage
nitp-build test

# Run only unit tests
nitp-build test:unit

# Run only integration tests
nitp-build test:integration

# Test specific module
nitp-build test --module=admin
```

### Quality Assurance

```bash
# Run all quality checks
nitp-build quality

# Format code using Spotless
nitp-build format

# Quality check with verbose output
nitp-build quality --verbose
```

### Development Commands

```bash
# Start Admin API server
nitp-build start:admin

# Start TNP API server
nitp-build start:tnp

# Start with specific environment
nitp-build start:admin --env=test
```

### Docker Commands

```bash
# Start all services with Docker
nitp-build docker:up
```

### Utility Commands

```bash
# Show system information
nitp-build info

# Check system health
nitp-build doctor

# Show help
nitp-build --help
```

## ⚙️ Configuration

The build system uses a comprehensive configuration file (`lib/nitp-build-v2.json`) that defines:

- **Scripts**: Available build commands and their Maven configurations
- **Modules**: Project structure and dependencies
- **Environments**: Environment-specific settings and properties
- **Coverage**: Code coverage thresholds and reporting
- **Quality**: Code quality tools and standards

### Modules

| Module | Type | Description | Coverage Threshold |
|--------|------|-------------|-------------------|
| `nitp-core` | Library | Core shared functionality | 80% lines, 70% branches |
| `nitp-admin-api` | Application | Administrative API | 75% lines, 65% branches |
| `nitp-tnp-api` | Application | Training & Placement API | 75% lines, 65% branches |

## 🌍 Environments

### Development Environment (`dev`)
- **Profile**: `spring.profiles.active=dev`
- **Database**: MySQL localhost
- **Logging**: DEBUG level
- **JVM**: `-Xmx512m`

```bash
nitp-build build --env=dev
```

### Test Environment (`test`)
- **Profile**: `spring.profiles.active=test`
- **Database**: H2 in-memory
- **Logging**: INFO level
- **JVM**: `-Xmx256m`

```bash
nitp-build test --env=test
```

### Production Environment (`prod`)
- **Profile**: `spring.profiles.active=prod`
- **Database**: Production MySQL
- **Logging**: WARN level
- **JVM**: `-Xmx1024m -XX:+UseG1GC`

```bash
nitp-build build --env=prod
```

## 📊 Code Coverage

Coverage reports are automatically generated using JaCoCo:

### Report Locations
- **HTML Report**: `target/site/jacoco/index.html`
- **XML Report**: `target/site/jacoco/jacoco.xml`
- **CSV Report**: `target/site/jacoco/jacoco.csv`

### Coverage Thresholds
- **Core Module**: 80% line coverage, 70% branch coverage
- **API Modules**: 75% line coverage, 65% branch coverage

### Viewing Coverage Reports

```bash
# Run tests to generate coverage
nitp-build test

# Open HTML report (Windows)
start target/site/jacoco/index.html

# Open HTML report (macOS)
open target/site/jacoco/index.html

# Open HTML report (Linux)
xdg-open target/site/jacoco/index.html
```

## 🔍 Quality Standards

### Code Formatting
- **Tool**: Spotless
- **Standards**: Google Java Style Guide
- **Command**: `nitp-build format`

### Static Analysis
- **CheckStyle**: Java coding standards
- **PMD**: Programming mistake detector
- **SpotBugs**: Bug pattern detection

### Testing Framework
- **Framework**: JUnit 5
- **Parallel Execution**: Enabled
- **Failure Reruns**: Enabled for stability

## 🐛 Troubleshooting

### Common Issues

#### Command Not Found
```bash
# Check if npm global bin is in PATH
npm config get prefix

# Manually add to PATH (Linux/macOS)
export PATH="$(npm config get prefix)/bin:$PATH"

# Manually add to PATH (Windows)
set PATH=%PATH%;%APPDATA%\npm
```

#### Permission Denied (Unix Systems)
```bash
# Fix npm permissions
sudo npm install -g @nitp/build-tools

# Or use npx
npx @nitp/build-tools build
```

#### Java/Maven Not Found
```bash
# Check Java installation
java -version

# Check Maven installation
mvn -v

# Install Java (Ubuntu/Debian)
sudo apt update
sudo apt install openjdk-17-jdk

# Install Maven (Ubuntu/Debian)
sudo apt install maven
```

#### Build Failures
```bash
# Check system requirements
nitp-build doctor

# Run with verbose output
nitp-build build --verbose

# Clean and rebuild
mvn clean
nitp-build build
```

### Getting Help

1. **Check Documentation**: Read this README thoroughly
2. **Run Diagnostics**: Use `nitp-build doctor` to check system health
3. **Verbose Output**: Add `--verbose` flag to any command for detailed logs
4. **Check Issues**: Visit [GitHub Issues](https://github.com/ashishkr375/adminportal_updated_new/issues)
5. **Contact Developer**: Reach out via [LinkedIn](https://www.linkedin.com/in/ashish-kumar-nitp/)

## 🤝 Contributing

We welcome contributions to improve the NITP Build System!

### Development Setup

```bash
# Clone the repository
git clone https://github.com/ashishkr375/adminportal_updated_new.git

# Navigate to build tools
cd adminportal_updated_new/backend/nitp-build-tools

# Install dependencies
npm install

# Link for local development
npm link
```

### Contribution Guidelines

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

### Code Standards

- Follow existing code style
- Add tests for new features
- Update documentation
- Ensure all tests pass

## 📜 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **NIT Patna** for providing the platform and support
- **Open Source Community** for the amazing tools and libraries
- **Contributors** who have helped improve this project

## 📞 Contact & Support

- **Developer**: [Ashish Kumar](https://github.com/ashishkr375)
- **Email**: [Contact via GitHub](https://github.com/ashishkr375)
- **LinkedIn**: [https://www.linkedin.com/in/ashish-kumar-nitp/](https://www.linkedin.com/in/ashish-kumar-nitp/)
- **Project Repository**: [https://github.com/ashishkr375/adminportal_updated_new](https://github.com/ashishkr375/adminportal_updated_new)
- **Issues**: [Report Issues](https://github.com/ashishkr375/adminportal_updated_new/issues)

---

<div align="center">

**Made with ❤️ by [Ashish Kumar](https://github.com/ashishkr375) at NIT Patna**

[![GitHub](https://img.shields.io/badge/GitHub-ashishkr375-blue?style=social&logo=github)](https://github.com/ashishkr375)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Ashish%20Kumar-blue?style=social&logo=linkedin)](https://www.linkedin.com/in/ashish-kumar-nitp/)

</div>