npm package: @gitconductor/core
Description: Core rule engine, git layer, AI providers, and interceptor for gitconductor
Author: gitconductor contributors
Latest version: 0.1.5

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

```bash
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

```typescript
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

```typescript
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`](https://www.npmjs.com/package/@gitconductor/cli) for the full configuration reference and user-facing CLI.

## Links

- [Documentation](https://gitconductor.dev)
- [GitHub](https://github.com/itsshirazhere/gitconductor)
- [`@gitconductor/cli`](https://www.npmjs.com/package/@gitconductor/cli) — user-facing CLI

## License

MIT