tessl/npm-cz-git

A better customizable and git support commitizen adapter

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Configuration Loading

Name: tessl/npm-cz-git
Author: tessl

Flexible configuration loading system supporting multiple file formats and locations.

Capabilities

Main Configuration Loader

Primary function for loading both commitizen and commitlint configurations from various sources.

/**
 * Entry function for loading both commitizen and commitlint configurations
 * @param options - Loading options including cwd and explicit config path
 * @returns Promise resolving to merged configuration object
 */
function configLoader(options?: UserOptions): Promise<{
  rules?: Partial<RulesConfig>;
  prompt?: CommitizenGitOptions;
}>;

interface UserOptions {
  /** Debug mode working directory */
  cwd?: string;
  
  /** Directly specify the configuration path */
  configPath?: string;
}

Usage Examples:

import { configLoader } from "cz-git";

// Load configuration from default locations
const config = await configLoader();

// Load from specific directory
const config = await configLoader({ cwd: '/path/to/project' });

// Load from explicit config file
const config = await configLoader({ 
  configPath: './custom-cz.config.js' 
});

// Access loaded configuration
console.log(config.prompt?.types);
console.log(config.rules?.['type-enum']);

Commitlint Configuration Loader

Specialized loader for commitlint configuration files.

/**
 * Load commitlint configuration from various file formats
 * @param cwd - Working directory to search from
 * @returns Promise resolving to commitlint configuration
 */
function clLoader(cwd?: string): Promise<CommitlintOptions>;

interface CommitlintOptions {
  /** Commitlint validation rules */
  rules?: Partial<RulesConfig>;
  
  /** Prompt configuration from commitlint */
  prompt?: any;
}

Supported File Names:

package.json (commitlint field)
.commitlintrc
.commitlintrc.json
.commitlintrc.yaml / .commitlintrc.yml
.commitlintrc.js / .commitlintrc.cjs / .commitlintrc.mjs
.commitlintrc.ts / .commitlintrc.cts / .commitlintrc.mts
commitlint.config.js / commitlint.config.cjs / commitlint.config.mjs
commitlint.config.ts / commitlint.config.cts / commitlint.config.mts

Commitizen Configuration Loader

Specialized loader for commitizen-specific configuration files.

/**
 * Load commitizen configuration from various sources
 * @param cwd - Working directory to search from
 * @returns Promise resolving to commitizen configuration
 */
function czLoader(cwd?: string): Promise<CommitizenGitOptions>;

Supported File Names:

.czrc
cz.config.js / cz.config.cjs / cz.config.mjs
cz.config.ts / cz.config.cts / cz.config.mts
package.json (config.commitizen field)

AI Configuration Loader

Loader for AI-specific configuration stored in user's home directory.

/**
 * Load AI configuration from user home directory
 * @returns Promise resolving to AI configuration
 */
function aiLoader(): Promise<{
  openAIToken: string;
  apiEndpoint: string;
  apiProxy: string;
  apiModel: string;
}>;

Configuration Locations:

~/.config/.czrc
~/.czrc

Usage Examples:

import { aiLoader } from "cz-git";

// Load AI configuration
const aiConfig = await aiLoader();

console.log(aiConfig.openAIToken); // API token if set
console.log(aiConfig.apiModel);    // Preferred model

Generic Configuration Loader

Low-level loader for custom configuration loading needs.

/**
 * Generic configuration loader using cosmiconfig
 * @param options - Loader configuration options
 * @returns Promise resolving to configuration result or null
 */
function loader(options: LoaderOptions): Promise<{
  config: any;
  filepath: string;
} | null>;

interface LoaderOptions {
  /** Module name for cosmiconfig */
  moduleName: string;
  
  /** Working directory to search from */
  cwd?: string;
  
  /** Stop searching at this directory */
  stopDir?: string;
  
  /** Explicit file path to load */
  explicitPath?: string;
  
  /** File names to search for */
  searchPlaces?: string[];
  
  /** Package.json property path */
  packageProp?: string[];
}

Usage Examples:

import { loader } from "cz-git";

// Custom configuration loading
const result = await loader({
  moduleName: 'mycommit',
  searchPlaces: ['.mycommitrc', 'mycommit.config.js'],
  packageProp: ['config', 'mycommit']
});

if (result) {
  console.log('Config found at:', result.filepath);
  console.log('Config content:', result.config);
}

Configuration File Formats

All loaders support multiple file formats through cosmiconfig:

interface SupportedFormats {
  /** JSON configuration files */
  json: '.json' | '.commitlintrc' | '.czrc';
  
  /** YAML configuration files */  
  yaml: '.yaml' | '.yml';
  
  /** JavaScript configuration files */
  javascript: '.js' | '.cjs' | '.mjs';
  
  /** TypeScript configuration files */
  typescript: '.ts' | '.cts' | '.mts';
  
  /** Package.json fields */
  packageJson: 'package.json';
}

Configuration Examples:

// cz.config.js
export default {
  types: [
    { value: 'feat', name: 'feat: New feature' },
    { value: 'fix', name: 'fix: Bug fix' }
  ],
  useEmoji: true,
  scopes: ['core', 'ui', 'api']
};

// .commitlintrc.js  
export default {
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'docs']],
  },
  prompt: {
    messages: {
      type: 'Select the type of change:'
    }
  }
};

// package.json
{
  "config": {
    "commitizen": {
      "path": "cz-git",
      "czConfig": "./cz.config.js"
    }
  }
}

# .commitlintrc.yml
rules:
  type-enum:
    - 2
    - always
    - [feat, fix, docs, style, refactor]
prompt:
  useEmoji: true
  emojiAlign: center

Configuration Merging

The configuration system merges configurations in priority order:

Explicit config path (highest priority)
Commitizen configuration (cz-specific settings)
Commitlint prompt configuration (commitlint's prompt field)
AI configuration (user-global AI settings)
Default configuration (lowest priority)

interface ConfigurationMerging {
  /** Final merged configuration priority */
  priority: [
    'explicitPath',
    'czConfig', 
    'commitlintPrompt',
    'aiConfig',
    'defaults'
  ];
}

Configuration Validation

The loader system includes configuration validation and error handling:

Syntax Errors: Clear error messages for malformed configuration files
Type Validation: Runtime validation of configuration structure
Extends Resolution: Automatic resolution of commitlint extends configurations
Executable Configs: Support for function-based configurations

Debug Mode

Enable debug logging to troubleshoot configuration loading:

# Enable debug mode
CZ_DEBUG=1 npx cz

# Output shows:
# commitlint config-file: /project/.commitlintrc.js
# cz config-file: /project/cz.config.js
# Specify config file: /custom/path/config.js

The configuration loading system is designed to be flexible, allowing projects to use any combination of configuration files while maintaining compatibility with existing commitlint and commitizen setups.