API Reference

import { Branchwright } from '@branchwright/cli';

const branchwright = new Branchwright(config?);

new Branchwright(config?: BranchwrightConfig)

const result = await branchwright.validate('feat/user-auth');

if (result.valid) {
  console.log('✓ Branch name is valid');
} else {
  console.log(`✗ ${result.message}`);
  console.log('Suggestions:', result.suggestions);
}

const branchName = await branchwright.create();
console.log(`Created: ${branchName}`);

// Lint current branch
const results = await branchwright.lint();

// Lint all branches
const allResults = await branchwright.lint({ all: true });

// Lint specific branches
const specificResults = await branchwright.lint({ 
  branches: ['feat/auth', 'fix/bug'] 
});

interface BranchwrightConfig {
  branchTypes?: BranchTypeOption[];
  template?: string;
  maxDescriptionLength?: number;
  descriptionStyle?: 'kebab-case' | 'snake_case' | 'camelCase' | 'PascalCase';
  ignoredBranches?: string[];
  rules?: Rules;
  extraQuestions?: InteractiveQuestions;
  questions?: QuestionConfig;
  plugins?: string[];
  presets?: string[];
  showCliTips?: boolean;
}

interface BranchTypeOption {
  name: string;   // Short identifier (feat, fix, etc.)
  label: string;  // Display name for prompts
}

interface ValidationResult {
  valid: boolean;
  message?: string;
  suggestions?: string[];
  violations?: RuleViolation[];
}

interface LintOptions {
  all?: boolean;
  branches?: string[];
  json?: boolean;
}

interface LintResult {
  branch: string;
  valid: boolean;
  message?: string;
  violations?: RuleViolation[];
}

import { defineRule } from '@branchwright/cli';

const myRule = defineRule(
  {
    id: 'my-rule',
    meta: {
      title: 'My Custom Rule',
      description: 'Validates something specific',
    },
    defaultSeverity: 'required',
  },
  (context: RuleContext) => {
    // Return null if valid
    if (isValid(context.branchName)) {
      return null;
    }
    
    // Return violation if invalid
    return {
      message: 'Branch name is invalid',
      suggestions: ['alternative-name'],
    };
  }
);

interface RuleContext {
  branchName: string;
  config: BranchwrightConfig;
  options?: any;  // Rule-specific options
}

import { evaluateRules, coreRuleRegistry } from '@branchwright/cli';

const violations = await evaluateRules(
  'feat/my-branch',
  config,
  coreRuleRegistry
);

violations.forEach(v => {
  console.error(`${v.ruleId}: ${v.message}`);
});

import { createRegistry, coreRuleRegistry } from '@branchwright/cli';

const customRegistry = createRegistry(
  ...coreRuleRegistry.entries(),
  myCustomRule,
  anotherCustomRule
);

import { defineConfig } from '@branchwright/cli';

export default defineConfig({
  // Full TypeScript autocomplete and validation
  branchTypes: [/* ... */],
  template: '{{type}}/{{desc}}',
});

import { loadConfig } from '@branchwright/cli';

const config = await loadConfig('./path/to/config.ts');

#!/usr/bin/env node
import { Branchwright } from '@branchwright/cli';

async function main() {
  const brw = new Branchwright();
  
  if (process.argv[2] === 'validate') {
    const branch = process.argv[3] || getCurrentBranch();
    const result = await brw.validate(branch);
    process.exit(result.valid ? 0 : 1);
  }
}

main();

import express from 'express';
import { Branchwright } from '@branchwright/cli';

const app = express();
const brw = new Branchwright();

app.post('/validate-branch', async (req, res) => {
  const { branchName } = req.body;
  const result = await brw.validate(branchName);
  
  res.json({
    valid: result.valid,
    message: result.message,
  });
});

import { Branchwright } from '@branchwright/cli';
import * as core from '@actions/core';

async function run() {
  try {
    const brw = new Branchwright();
    const branch = process.env.GITHUB_HEAD_REF;
    const result = await brw.validate(branch);
    
    if (!result.valid) {
      core.setFailed(result.message);
    }
  } catch (error) {
    core.setFailed(error.message);
  }
}

run();

#!/usr/bin/env node
import { Branchwright } from '@branchwright/cli';
import { execSync } from 'child_process';

async function validateCurrentBranch() {
  const brw = new Branchwright();
  const branch = execSync('git branch --show-current')
    .toString()
    .trim();
  
  const result = await brw.validate(branch);
  
  if (!result.valid) {
    console.error(`✗ Invalid branch name: ${result.message}`);
    process.exit(1);
  }
  
  console.log('✓ Branch name is valid');
}

validateCurrentBranch();

import { Validator } from '@branchwright/cli';

class CustomValidator extends Validator {
  async validate(branchName: string) {
    // Custom validation logic
    const result = await super.validate(branchName);
    
    // Add additional checks
    if (branchName.includes('temp')) {
      return {
        valid: false,
        message: 'Temporary branches not allowed',
      };
    }
    
    return result;
  }
}

// my-plugin.ts
import { defineRule } from '@branchwright/cli';

export default [
  defineRule(
    {
      id: 'team-prefix',
      meta: {
        title: 'Team prefix required',
        description: 'Branch must start with team name',
      },
      defaultSeverity: 'required',
    },
    (context) => {
      const { team } = context.options;
      if (!context.branchName.startsWith(`${team}/`)) {
        return {
          message: `Branch must start with ${team}/`,
          suggestions: [`${team}/${context.branchName}`],
        };
      }
      return null;
    }
  ),
  // More rules...
];

// Usage in config
export default defineConfig({
  plugins: ['./my-plugin.ts'],
  rules: {
    'team-prefix': ['required', { team: 'frontend' }],
  },
});