nitp-build-tools

@nitp/build-tools

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

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

📋 Table of Contents

• Features
• Installation
• Quick Start
• Requirements
• Commands
• Configuration
• Environments
• Code Coverage
• Quality Standards
• Troubleshooting
• Contributing
• 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)

npm install -g @nitp/build-tools

Project-Specific Installation

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

Verify Installation

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

🚀 Quick Start

# 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

# 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

# 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

# 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

# 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

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

Utility Commands

# 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

nitp-build build --env=dev

Test Environment (test)

• Profile: spring.profiles.active=test
• Database: H2 in-memory
• Logging: INFO level
• JVM: -Xmx256m

nitp-build test --env=test

Production Environment (prod)

• Profile: spring.profiles.active=prod
• Database: Production MySQL
• Logging: WARN level
• JVM: -Xmx1024m -XX:+UseG1GC

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

# 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

# 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)

# Fix npm permissions
sudo npm install -g @nitp/build-tools

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

Java/Maven Not Found

# 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

# Check system requirements
nitp-build doctor

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

# Clean and rebuild
mvn clean
nitp-build build

Getting Help

• Check Documentation: Read this README thoroughly
• Run Diagnostics: Use nitp-build doctor to check system health
• Verbose Output: Add --verbose flag to any command for detailed logs
• Check Issues: Visit GitHub Issues
• Contact Developer: Reach out via LinkedIn

🤝 Contributing

We welcome contributions to improve the NITP Build System!

Development Setup

# 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

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• 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 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
• Email: Contact via GitHub
• LinkedIn: https://www.linkedin.com/in/ashish-kumar-nitp/
• Project Repository: https://github.com/ashishkr375/adminportal_updated_new
• Issues: Report Issues

Made with ❤️ by Ashish Kumar at NIT Patna