The standalone validation engine behind git-hygiene.

@chitrank2050/git-hygiene-core provides the core validation logic for modern Git workflows. Built as a Native ESM engine for Node.js 24 (Stable), it offers high-performance validation with zero external dependencies (built on top of the standard commitlint engine).

🧩 Ecosystem

| Package | Role | Status | | :--------------------------------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @chitrank2050/git-hygiene | CLI & Action | | | @chitrank2050/git-hygiene-core | Standalone Engine | |

Features ✨

• Conventional Commits: Full support for standard conventional commit validation.
• Branch Names: Powerful regex-based branch name enforcement.
• PR Titles: Validates pull request metadata for clean repository history.
• Context Aware: Automatically detects rules from your package.json.

📦 Installation

# Using pnpm
pnpm add @chitrank2050/git-hygiene-core

# Using JSR
npx jsr add @chitrank2050/git-hygiene-core

# Using npm
npm install @chitrank2050/git-hygiene-core

🛠️ Usage

import {
  validateBranch,
  validateTitle,
  validateCommit,
  resolveConfig,
  getRecommendedBump,
} from '@chitrank2050/git-hygiene-core';

// 1. Validate a branch name
const branchResult = await validateBranch('feat/add-login');
if (!branchResult.valid) {
  console.error(`Invalid branch: ${branchResult.message}`);
}

// 2. Validate a PR title
const titleResult = await validateTitle('feat: implement oauth2');
console.log(`Title valid: ${titleResult.valid}`);

// 3. Validate a commit message (Async)
// Returns a detailed report including commitlint warnings/errors
const commitResult = await validateCommit('fix: resolve memory leak');
if (commitResult.valid) {
  console.log('✅ Commit follows standards');
} else {
  console.log('❌ Commit validation failed:');
  commitResult.errors.forEach(err => console.log(`- ${err.message}`));
}

// 4. Suggest a semantic version bump
const bump = await getRecommendedBump();
console.log(`Recommended bump: ${bump.releaseType} (Reason: ${bump.reason})`);

// 5. Programmatic usage with config override
const customConfig = await resolveConfig({ types: ['feat', 'fix'], allowEmptyScope: false });
const result = await validateCommit('feat: manual override', customConfig);

⚙️ Configuration

git-hygiene is designed to be zero-config, but you can easily customize the engine by adding a git-hygiene block to your root package.json.

| Property | Description | Default | Possible Values | | ----------------- | -------------------------------------- | ------------------------------------------- | -------------------------------- | | types | Allowed commit types | feat, fix, chore, etc. | string[] | | ignoreBranches | Branches to skip validation | main, master, development, gh-pages | string[] | | maxHeaderLength | Max length of the commit header | 100 | number | | maxBodyLength | Max length of a single body line | 1000 | number | | minBodyLength | Min length of the commit body | 0 | number | | typeCase | Case requirement for types | lower-case | lower-case, upper-case, etc. | | scopeCase | Case requirement for scopes | lower-case | lower-case, upper-case, etc. | | allowEmptyScope | Whether scope is optional | true | boolean | | subjectFullStop | Whether subject can end with a period | never | always, never | | extends | Standard configs to extend from | [] | string[] | | rules | Raw commitlint rules to merge/override | {} | Record<string, unknown> |

{
  "git-hygiene": {
    "extends": ["@commitlint/config-conventional"],
    "types": ["feat", "fix", "chore", "docs", "refactor", "test", "renovate"],
    "ignoreBranches": ["main", "develop", "release/*"],
    "maxHeaderLength": 100,
    "allowEmptyScope": false,
    "rules": {
      "subject-case": [2, "always", "sentence-case"]
    }
  }
}

📜 License

MIT - see LICENSE for details.