branch-validator-pro 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjib Roy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# 🔍 Branch Validator Pro
+
+A lightweight Node.js package that validates Git branch names and commit messages following consistent conventions and best practices.
+
+## 🚀 Overview
+
+Branch Validator Pro enforces consistent Git naming conventions across your team, ensuring code quality and maintainability through automated validation of branch names and commit messages.
+
+## ✨ Features
+
+- ✅ **Git branch name validation** with proper prefixes (feature/, bugfix/, hotfix/, release/, chore/)
+- ✅ **Commit message validation** following consistent patterns
+- ✅ **Command-line interface** for easy integration
+- ✅ **Programmatic API** for custom implementations
+- ✅ **Git hook integration** for automated validation
+- ✅ **Zero dependencies** for minimal footprint
+
+## 📦 Installation
+
+### Global Installation (Recommended)
+```bash
+npm install -g branch-validator-pro
+```
+
+### Local Installation
+```bash
+npm install branch-validator-pro
+```
+
+## 🎯 Quick Start
+
+### Basic Usage
+```bash
+# Validate branch names
+validate-git branch feature/SHOP-1234-add-user-authentication
+validate-git branch bugfix/SHOP-5678-fix-login-bug
+validate-git branch hotfix/SHOP-9012-critical-security-patch
+
+# Validate commit messages
+validate-git commit SHOP-1234-add-user-authentication
+validate-git commit SHOP-5678-fix-login-bug
+```
+
+### Output
+```
+✅ Branch name is valid: feature/SHOP-1234-add-user-authentication
+✅ Commit message is valid: SHOP-1234-fix-login-bug
+```
+
+## 📖 Programmatic Usage
+
+```javascript
+const { validateBranchName, validateCommitMessage } = require('branch-validator-pro');
+
+// Validate branch name
+const branchResult = validateBranchName('feature/SHOP-1234-new-feature');
+console.log(branchResult.valid); // true/false
+console.log(branchResult.message); // validation message
+
+// Validate commit message
+const commitResult = validateCommitMessage('SHOP-1234-new-feature');
+console.log(commitResult.valid); // true/false
+console.log(commitResult.message); // validation message
+```
+
+## 📋 Validation Rules
+
+### Branch Names
+- Must start with one of these prefixes:
+  - `feature/` - for new features
+  - `bugfix/` - for bug fixes
+  - `hotfix/` - for critical fixes
+  - `release/` - for release branches
+  - `chore/` - for maintenance tasks
+- Must contain a ticket pattern: `SHOP-XXXX` (where XXXX is a number)
+- Description must be lowercase
+- Use dashes (-) only, no spaces or underscores
+- **Pattern:** `^[a-z]+/SHOP-\d+-[a-z0-9-]+$`
+
+**Valid Examples:**
+- `feature/SHOP-1234-add-payment-gateway`
+- `bugfix/SHOP-5678-fix-validation-error`
+- `hotfix/SHOP-9012-security-patch`
+
+**Invalid Examples:**
+- `feature/add-payment` (missing ticket)
+- `Feature/SHOP-1234-payment` (uppercase prefix)
+- `feature/SHOP-1234_payment_gateway` (underscores not allowed)
+- `feature/SHOP-1234-Payment Gateway` (spaces not allowed)
+
+### Commit Messages
+- Must follow the pattern: `SHOP-XXXX-description`
+- Use lowercase letters, numbers, and dashes only
+- No spaces or underscores allowed
+- **Pattern:** `^SHOP-\d+-[a-z0-9-]+$`
+
+**Valid Examples:**
+- `SHOP-1234-implement-user-registration`
+- `SHOP-5678-fix-database-connection`
+- `SHOP-9012-update-security-headers`
+
+**Invalid Examples:**
+- `SHOP-1234 implement user registration` (spaces not allowed)
+- `SHOP-1234_implement_user_registration` (underscores not allowed)
+- `implement user registration` (missing ticket)
+
+## 🪝 Git Hook Integration
+
+Integrate this validator with Git hooks for automatic validation on every commit.
+
+### Pre-commit Hook
+Create `.git/hooks/pre-commit`:
+```bash
+#!/bin/bash
+branch_name=$(git symbolic-ref --short HEAD)
+validate-git branch "$branch_name"
+exit_code=$?
+if [ $exit_code -ne 0 ]; then
+    echo "Branch name validation failed!"
+    exit 1
+fi
+```
+
+### Commit Message Hook
+Create `.git/hooks/commit-msg`:
+```bash
+#!/bin/bash
+commit_msg=$(cat $1)
+validate-git commit "$commit_msg"
+exit_code=$?
+if [ $exit_code -ne 0 ]; then
+    echo "Commit message validation failed!"
+    exit 1
+fi
+```
+
+Make hooks executable:
+```bash
+chmod +x .git/hooks/pre-commit
+chmod +x .git/hooks/commit-msg
+```
+
+## 🔌 API Reference
+
+### validateBranchName(branchName)
+
+Validates a Git branch name against the defined rules.
+
+**Parameters:**
+- `branchName` (string): The branch name to validate
+
+**Returns:**
+- `valid` (boolean): Whether the branch name is valid
+- `message` (string): Validation result message
+
+### validateCommitMessage(commitMessage)
+
+Validates a commit message against the defined rules.
+
+**Parameters:**
+- `commitMessage` (string): The commit message to validate
+
+**Returns:**
+- `valid` (boolean): Whether the commit message is valid
+- `message` (string): Validation result message
+
+## 🚪 Exit Codes
+
+- `0`: Validation successful
+- `1`: Validation failed or invalid usage
+
+## 📝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Commit your changes: `git commit -m "your-feature-description"`
+4. Push to the branch: `git push origin feature/your-feature`
+5. Submit a pull request
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 👤 Author
+
+### **✨ Sanjib Roy**
+
+A passionate developer focused on building tools that enhance developer productivity and code quality.
+
+**Connect with me:**
+- 🌐 **GitHub:** [@snbroy](https://github.com/snbroy)
+- 💼 **LinkedIn:** [Sanjib Roy](https://www.linkedin.com/in/sanjib-r-834947100/)
+- 📧 **Email:** [sanjibroy17061995@gmail.com](mailto:sanjibroy17061995@gmail.com)
+- 📱 **Mobile:** +91 8918132291
+
+## 💬 Support
+
+For issues or questions, please reach out:
+- 📧 Email: [sanjibroy17061995@gmail.com](mailto:sanjibroy17061995@gmail.com)
+- 📱 Mobile: +91 8918132291
+- 🐛 [Open an issue](https://github.com/snbroyvfc95/branch-validator-pro/issues) on GitHub
+
+## 📚 Changelog
+
+### v1.0.0
+- Initial release
+- Branch name validation
+- Commit message validation
+- CLI interface
+- Programmatic API
+- Git hook integration support

package/cli.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+const { 
+  validateBranchName, 
+  validateCommitMessage, 
+  validateBoth,
+  showConfig
+} = require('./index.js');
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.log('🎫 Simple Branch & Commit Validator');
+  console.log('');
+  console.log('Usage:');
+  console.log('  validate-git branch <branch-name>     - Validate branch name format');
+  console.log('  validate-git commit <commit-message>  - Validate commit message format');
+  console.log('  validate-git both <branch> <commit>   - Validate both branch and commit');
+  console.log('  validate-git config                   - Show current configuration');
+  console.log('');
+  console.log('Examples:');
+  console.log('  validate-git branch "feature/SHOP-1234-fix-user-login"');
+  console.log('  validate-git commit "SHOP-1234-fix-user-login"');
+  console.log('  validate-git both "feature/SHOP-1234-fix-bug" "SHOP-1234-fix-bug"');
+  console.log('');
+  console.log('Environment Variables:');
+  console.log('  PROJECT_KEYS      - Comma-separated project keys (default: SHOP,PROJ,TASK)');
+  console.log('  SKIP_VALIDATION   - Set to "true" to skip validation entirely');
+  console.log('');
+  process.exit(1);
+}
+
+const command = args[0];
+
+async function runValidation() {
+  try {
+    switch (command) {
+      case 'branch': {
+        const branchName = args[1];
+        if (!branchName) {
+          console.log('❌ Error: Please provide a branch name to validate');
+          console.log('Usage: validate-git branch <branch-name>');
+          console.log('Example: validate-git branch "feature/SHOP-1234-fix-user-login"');
+          process.exit(1);
+        }
+        
+        console.log(`🔍 Validating branch: ${branchName}`);
+        const result = validateBranchName(branchName);
+        
+        console.log('\\n' + result.message);
+        if (result.suggestion) {
+          console.log(`💡 Suggestion: ${result.suggestion}`);
+        }
+        
+        if (result.ticketId) {
+          console.log(`🎫 Ticket ID: ${result.ticketId}`);
+        }
+        
+        process.exit(result.valid ? 0 : 1);
+      }
+      
+      case 'commit': {
+        const commitMessage = args[1];
+        if (!commitMessage) {
+          console.log('❌ Error: Please provide a commit message to validate');
+          console.log('Usage: validate-git commit <commit-message>');
+          console.log('Example: validate-git commit "SHOP-1234-fix-user-login"');
+          process.exit(1);
+        }
+        
+        console.log(`📝 Validating commit: ${commitMessage}`);
+        const result = validateCommitMessage(commitMessage);
+        
+        console.log('\\n' + result.message);
+        if (result.suggestion) {
+          console.log(`💡 Suggestion: ${result.suggestion}`);
+        }
+        
+        if (result.ticketId) {
+          console.log(`🎫 Ticket ID: ${result.ticketId}`);
+        }
+        
+        process.exit(result.valid ? 0 : 1);
+      }
+      
+      case 'both': {
+        const branchName = args[1];
+        const commitMessage = args[2];
+        if (!branchName || !commitMessage) {
+          console.log('❌ Error: Please provide both branch name and commit message');
+          console.log('Usage: validate-git both <branch-name> <commit-message>');
+          console.log('Example: validate-git both "feature/SHOP-1234-fix-bug" "SHOP-1234-fix-bug"');
+          process.exit(1);
+        }
+        
+        console.log(`🔄 Validating both branch and commit...`);
+        const result = validateBoth(branchName, commitMessage);
+        
+        console.log('\\n📊 Validation Results:');
+        console.log(`🌿 Branch: ${result.branchResult.valid ? '✅' : '❌'} ${result.branchResult.message}`);
+        console.log(`💬 Commit: ${result.commitResult.valid ? '✅' : '❌'} ${result.commitResult.message}`);
+        
+        if (result.branchResult.suggestion) {
+          console.log(`💡 Branch suggestion: ${result.branchResult.suggestion}`);
+        }
+        if (result.commitResult.suggestion) {
+          console.log(`💡 Commit suggestion: ${result.commitResult.suggestion}`);
+        }
+        
+        console.log(`\\n🎯 Overall: ${result.valid ? '✅ Valid' : '❌ Invalid'}`);
+        
+        process.exit(result.valid ? 0 : 1);
+      }
+      
+      case 'config': {
+        const result = showConfig();
+        process.exit(0);
+      }
+      
+      default: {
+        console.log(`❌ Unknown command: ${command}`);
+        console.log('Run "validate-git" without arguments to see usage information.');
+        process.exit(1);
+      }
+    }
+  } catch (error) {
+    console.error('❌ Validation error:', error.message);
+    process.exit(1);
+  }
+}
+
+runValidation();

package/index.js

@@ -0,0 +1,285 @@
+/**
+ * Simple Branch Name and Commit Message Validator
+ * 
+ * Features:
+ * - Validates branch name format and patterns
+ * - Validates commit message format
+ * - Supports multiple project keys
+ * - Simple format validation without external API calls
+ * 
+ * Rules:
+ * - Branch name must start with feature/, bugfix/, hotfix/, release/, or chore/
+ * - Must contain a valid ticket pattern like SHOP-1234
+ * - Description must be lowercase, use dashes (-), no spaces or underscores
+ * - Commit message must follow: SHOP-1234-description format
+ * 
+ * Environment Variables:
+ * - PROJECT_KEYS: Comma-separated list of valid project keys (default: SHOP,PROJ,TASK)
+ * - SKIP_VALIDATION: Set to 'true' to skip validation entirely
+ */
+
+// Load environment variables from .env file if available
+try {
+  require('dotenv').config();
+} catch (e) {
+  // dotenv not available, use system environment variables
+}
+
+const fs = require('fs');
+const path = require('path');
+
+// Basic Configuration
+const CONFIG = {
+  projectKeys: (process.env.PROJECT_KEYS || 'SHOP,PROJ,TASK').split(',').map(key => key.trim()),
+  skipValidation: process.env.SKIP_VALIDATION === 'true'
+};
+
+// Simple validation patterns
+const PATTERNS = {
+  branch: /^(feature|bugfix|hotfix|release|chore)\/([A-Z]+)-(\d+)-(.+)$/,
+  commit: /^([A-Z]+)-(\d+)-(.+)$/,
+  ticketId: /([A-Z]+)-(\d+)/
+};
+
+/**
+ * Extract ticket ID from branch or commit name
+ */
+function extractTicketId(name) {
+  const matches = name.match(PATTERNS.ticketId);
+  return matches ? matches[0] : null;
+}
+
+/**
+ * Get expected format description for error messages
+ */
+function getExpectedFormat(type) {
+  switch (type) {
+    case 'branch':
+      return `${CONFIG.projectKeys[0]}-1234-description (feature/bugfix/hotfix/release/chore prefix required)`;
+    case 'commit':
+      return `${CONFIG.projectKeys[0]}-1234-description`;
+    default:
+      return 'Valid format required';
+  }
+}
+
+/**
+ * Validate basic format patterns
+ */
+function validateFormat(name, type) {
+  const pattern = PATTERNS[type];
+  if (!pattern) return { valid: false, message: 'Unknown validation type' };
+  
+  const match = name.match(pattern);
+  if (!match) {
+    return {
+      valid: false,
+      message: `❌ Invalid ${type} format. Expected: ${getExpectedFormat(type)}`
+    };
+  }
+  
+  const ticketId = extractTicketId(name);
+  if (!ticketId) {
+    return {
+      valid: false,
+      message: `❌ No valid ticket ID found in ${type}`
+    };
+  }
+  
+  const projectKey = ticketId.split('-')[0];
+  if (!CONFIG.projectKeys.includes(projectKey)) {
+    return {
+      valid: false,
+      message: `❌ Invalid project key '${projectKey}'. Valid keys: ${CONFIG.projectKeys.join(', ')}`
+    };
+  }
+  
+  return {
+    valid: true,
+    message: `✅ ${type.charAt(0).toUpperCase() + type.slice(1)} format is valid`,
+    ticketId: ticketId,
+    projectKey: projectKey
+  };
+}
+
+/**
+ * Validate branch name format
+ */
+function validateBranchName(branchName) {
+  console.log(`🎫 Validating branch: ${branchName}`);
+  
+  // Skip validation if disabled
+  if (CONFIG.skipValidation) {
+    return {
+      valid: true,
+      message: '✅ Branch validation skipped (SKIP_VALIDATION=true)',
+      skipped: true
+    };
+  }
+
+  // Basic format validation
+  const formatResult = validateFormat(branchName, 'branch');
+  if (!formatResult.valid) {
+    return formatResult;
+  }
+
+  // Check description format (lowercase, dashes only)
+  const parts = branchName.match(PATTERNS.branch);
+  if (parts && parts[4]) {
+    const description = parts[4];
+    
+    // Check for spaces
+    if (description.includes(' ')) {
+      return {
+        valid: false,
+        message: '❌ Branch description cannot contain spaces. Use dashes (-) instead',
+        suggestion: `${parts[1]}/${parts[2]}-${parts[3]}-${description.replace(/\s+/g, '-')}`
+      };
+    }
+    
+    // Check for underscores
+    if (description.includes('_')) {
+      return {
+        valid: false,
+        message: '❌ Branch description cannot contain underscores. Use dashes (-) instead',
+        suggestion: `${parts[1]}/${parts[2]}-${parts[3]}-${description.replace(/_/g, '-')}`
+      };
+    }
+    
+    // Check for uppercase
+    if (description !== description.toLowerCase()) {
+      return {
+        valid: false,
+        message: '❌ Branch description must be lowercase',
+        suggestion: `${parts[1]}/${parts[2]}-${parts[3]}-${description.toLowerCase()}`
+      };
+    }
+  }
+
+  return {
+    valid: true,
+    message: `✅ Branch name is valid`,
+    ticketId: formatResult.ticketId,
+    projectKey: formatResult.projectKey
+  };
+}
+
+/**
+ * Validate commit message format
+ */
+function validateCommitMessage(commitMessage) {
+  console.log(`📝 Validating commit: ${commitMessage}`);
+  
+  // Skip validation if disabled
+  if (CONFIG.skipValidation) {
+    return {
+      valid: true,
+      message: '✅ Commit validation skipped (SKIP_VALIDATION=true)',
+      skipped: true
+    };
+  }
+
+  // Basic format validation
+  const formatResult = validateFormat(commitMessage, 'commit');
+  if (!formatResult.valid) {
+    return formatResult;
+  }
+
+  // Check description format (lowercase, dashes only)
+  const parts = commitMessage.match(PATTERNS.commit);
+  if (parts && parts[3]) {
+    const description = parts[3];
+    
+    // Check for spaces
+    if (description.includes(' ')) {
+      return {
+        valid: false,
+        message: '❌ Commit description cannot contain spaces. Use dashes (-) instead',
+        suggestion: `${parts[1]}-${parts[2]}-${description.replace(/\s+/g, '-')}`
+      };
+    }
+    
+    // Check for underscores  
+    if (description.includes('_')) {
+      return {
+        valid: false,
+        message: '❌ Commit description cannot contain underscores. Use dashes (-) instead',
+        suggestion: `${parts[1]}-${parts[2]}-${description.replace(/_/g, '-')}`
+      };
+    }
+    
+    // Check for uppercase
+    if (description !== description.toLowerCase()) {
+      return {
+        valid: false,
+        message: '❌ Commit description must be lowercase',
+        suggestion: `${parts[1]}-${parts[2]}-${description.toLowerCase()}`
+      };
+    }
+  }
+
+  return {
+    valid: true,
+    message: `✅ Commit message is valid`,
+    ticketId: formatResult.ticketId,
+    projectKey: formatResult.projectKey
+  };
+}
+
+/**
+ * Validate both branch and commit together
+ */
+function validateBoth(branchName, commitMessage) {
+  console.log(`🔄 Validating both branch and commit...`);
+  
+  const branchResult = validateBranchName(branchName);
+  const commitResult = validateCommitMessage(commitMessage);
+  
+  // Check if ticket IDs match
+  if (branchResult.valid && commitResult.valid && 
+      branchResult.ticketId && commitResult.ticketId &&
+      branchResult.ticketId !== commitResult.ticketId) {
+    return {
+      valid: false,
+      message: `❌ Ticket ID mismatch: Branch has ${branchResult.ticketId}, commit has ${commitResult.ticketId}`,
+      branchResult,
+      commitResult
+    };
+  }
+  
+  return {
+    valid: branchResult.valid && commitResult.valid,
+    message: branchResult.valid && commitResult.valid 
+      ? '✅ Both branch and commit are valid'
+      : '❌ Validation failed',
+    branchResult,
+    commitResult
+  };
+}
+
+/**
+ * Show configuration info
+ */
+function showConfig() {
+  console.log('\n🔧 Validator Configuration:');
+  console.log(`📋 Valid Project Keys: ${CONFIG.projectKeys.join(', ')}`);
+  console.log(`⏭️  Skip Validation: ${CONFIG.skipValidation}`);
+  console.log('\n📝 Expected Formats:');
+  console.log(`🌿 Branch: feature/${CONFIG.projectKeys[0]}-1234-description`);
+  console.log(`💬 Commit: ${CONFIG.projectKeys[0]}-1234-description`);
+  console.log('\n📚 Valid Prefixes: feature/, bugfix/, hotfix/, release/, chore/');
+  
+  return {
+    valid: true,
+    config: CONFIG
+  };
+}
+
+module.exports = {
+  validateBranchName,
+  validateCommitMessage,
+  validateBoth,
+  showConfig,
+  extractTicketId,
+  CONFIG
+};

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "branch-validator-pro",
+  "version": "1.0.0",
+  "description": "Professional Git branch and commit validator for consistent naming conventions. Validates format and ensures proper ticket ID patterns without external API dependencies. Perfect for teams worldwide.",
+  "main": "index.js",
+  "bin": {
+    "validate-git": "cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node cli.js",
+    "validate-branch": "node cli.js branch",
+    "validate-commit": "node cli.js commit",
+    "validate-both": "node cli.js both",
+    "config": "node cli.js config"
+  },
+  "keywords": [
+    "git",
+    "branch",
+    "commit",
+    "validator",
+    "naming",
+    "convention",
+    "validation",
+    "cli",
+    "git-hooks",
+    "branch-naming",
+    "commit-message",
+    "ticket-format",
+    "development-tools",
+    "format-validation",
+    "git-workflow",
+    "code-quality",
+    "devops",
+    "pro",
+    "branch-validator",
+    "git-validator",
+    "commit-validator",
+    "code-standards",
+    "linter",
+    "git-linter",
+    "branch-rules",
+    "git-conventions",
+    "semantic-versioning",
+    "code-review",
+    "team-tools",
+    "automation",
+    "ci-cd",
+    "continuous-integration",
+    "git-best-practices",
+    "code-organization",
+    "developer-tools",
+    "productivity",
+    "workflow-automation",
+    "git-management",
+    "branch-strategy",
+    "quality-assurance",
+    "qa-tools",
+    "testing-tools",
+    "node",
+    "nodejs",
+    "npm-package",
+    "open-source",
+    "lightweight",
+    "fast",
+    "efficient",
+    "zero-dependencies",
+    "standalone",
+    "easy-setup",
+    "easy-to-use",
+    "universal"
+  ],
+  "author": {
+    "name": "Sanjib Roy",
+    "email": "sanjibroy17061995@gmail.com",
+    "url": "https://github.com/snbroy",
+    "github": "https://github.com/snbroy",
+    "linkedin": "https://www.linkedin.com/in/sanjib-r-834947100/",
+    "phone": "+91 8918132291"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snbroyvfc95/branch-validator-pro.git"
+  },
+  "bugs": {
+    "url": "https://github.com/snbroyvfc95/branch-validator-pro/issues",
+    "email": "sanjibroy17061995@gmail.com"
+  },
+  "homepage": "https://github.com/snbroyvfc95/branch-validator-pro#readme",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "files": [
+    "index.js",
+    "cli.js",
+    "README.md"
+  ],
+  "preferGlobal": true,
+  "dependencies": {
+    "dotenv": "^16.3.1"
+  },
+  "devDependencies": {}
+}