@gitconductor/core

Rule engine, git layer, AI providers, and interceptor for gitconductor.

This is the internal core library used by @gitconductor/cli. It is published as a separate package so that developers can build custom integrations on top of the gitconductor rule engine.

Install

npm install @gitconductor/core

Requirements

• Node.js ≥ 18

What's in here

• Interceptor — orchestrates rule evaluation, user prompting, and git execution
• 13 built-in rules — force-push, secret detection, WIP commits, direct commits to protected branches, and more
• GitClient — reads repo state and executes git commands (implements IGitReader + IGitExecutor)
• GitContextBuilder — builds a RepoContext snapshot from live git state
• ConfigLoader — loads and merges YAML config from global and repo-level files
• AI providers — OpenAI, Anthropic, Ollama adapters (all optional)
• RiskClassifier — classifies git commands by risk level (none → critical)

Usage

import {
  Interceptor,
  GitClient,
  ConfigLoader,
  ForcePushProtectedBranchRule,
  SecretDetectionRule,
  NullAIProvider,
  type InterceptorOutput,
  type IUserPrompt,
} from '@gitconductor/core';

const config = await new ConfigLoader().load();
const gitBin = '/usr/bin/git';
const gitClient = new GitClient(gitBin, process.cwd());

const output: InterceptorOutput = {
  block: (msg, suggestion) => console.error(`BLOCKED: ${msg}`),
  warn: (msg, suggestion) => console.warn(`WARNING: ${msg}`),
  info: (msg) => console.log(msg),
  error: (msg) => console.error(msg),
  aiAnalysis: () => {},
};

const prompt: IUserPrompt = {
  confirm: async (message) => {
    // Implement your own confirmation UI
    return false;
  },
};

const interceptor = new Interceptor(
  [new ForcePushProtectedBranchRule(), new SecretDetectionRule()],
  new NullAIProvider(),
  gitClient,  // IGitReader
  gitClient,  // IGitExecutor
  config,
  prompt,
  output,
);

const result = await interceptor.intercept(['push', '--force', 'origin', 'main']);
process.exit(result.exitCode);

Writing custom rules

import { BaseRule } from '@gitconductor/core';
import type { ParsedCommand, RepoContext, RuleResult } from '@gitconductor/core';

export class NoBigCommitsRule extends BaseRule {
  name = 'noBigCommits';
  description = 'Warns when a single commit touches too many files';
  defaultSeverity = 'warn' as const;

  async evaluate(command: ParsedCommand, context: RepoContext): Promise<RuleResult> {
    if (command.verb !== 'commit') return { triggered: false };

    const fileCount = context.changedFiles.length;
    if (fileCount < 30) return { triggered: false };

    return {
      triggered: true,
      severity: this.getSeverity(context.config),
      message: `This commit touches ${fileCount} files — consider splitting it up`,
    };
  }
}

Configuration

See @gitconductor/cli for the full configuration reference and user-facing CLI.

Links

• Documentation
• GitHub
• @gitconductor/cli — user-facing CLI

License

MIT