or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

changelog-generation.md configuration.md git-operations.md github-integration.md index.md repository-analysis.md version-management.md

tile.json

Configuration Management

Flexible configuration system supporting multiple configuration sources and automatic resolution of git repository information. This module provides comprehensive configuration loading, validation, and resolution for all changelogen features.

Capabilities

Load Changelog Configuration

Loads and resolves configuration from multiple sources with intelligent defaults.

/**
 * Load and resolve changelog configuration from multiple sources
 * @param cwd - Working directory for configuration and git operations
 * @param overrides - Optional configuration overrides
 * @returns Promise resolving to fully resolved configuration
 */
function loadChangelogConfig(
  cwd: string,
  overrides?: Partial<ChangelogConfig>
): Promise<ResolvedChangelogConfig>;

Usage Examples:

import { loadChangelogConfig } from "changelogen";

// Basic configuration loading
const config = await loadChangelogConfig(process.cwd());

// With overrides
const customConfig = await loadChangelogConfig(process.cwd(), {
  from: "v1.0.0",
  to: "HEAD",
  output: "CHANGELOG.md",
  noAuthors: true
});

// For specific directory
const repoConfig = await loadChangelogConfig("/path/to/repo", {
  types: {
    feat: { title: "✨ Features", semver: "minor" },
    fix: { title: "🐛 Fixes", semver: "patch" }
  }
});

Resolve Changelog Configuration

Resolves configuration values by filling in defaults and auto-detecting repository information.

/**
 * Resolve configuration by applying defaults and auto-detection
 * @param config - Base configuration object
 * @param cwd - Working directory for resolution
 * @returns Promise resolving to resolved configuration
 */
function resolveChangelogConfig(
  config: ChangelogConfig,
  cwd: string
): Promise<ResolvedChangelogConfig>;

Configuration Sources

Configuration is loaded from multiple sources in order of precedence:

CLI Arguments/Function Overrides (highest priority)
Project Configuration Files:
- changelog.config.{ts,js,mjs,cjs}
- .changelogrc
- package.json (changelog field)
Environment Variables
Default Values (lowest priority)

Example Configuration Files:

// changelog.config.ts
export default {
  types: {
    feat: { title: "🚀 Features", semver: "minor" },
    fix: { title: "🐛 Bug Fixes", semver: "patch" },
    docs: { title: "📚 Documentation", semver: "patch" }
  },
  scopeMap: {
    "ui": "interface",
    "cli": "command-line"
  },
  excludeAuthors: ["dependabot[bot]", "renovate[bot]"],
  noAuthors: false,
  hideAuthorEmail: true
};

// .changelogrc
{
  "types": {
    "feat": { "title": "🚀 Features", "semver": "minor" },
    "fix": { "title": "🐛 Bug Fixes", "semver": "patch" }
  },
  "output": "CHANGELOG.md",
  "excludeAuthors": ["bot@example.com"]
}

// package.json
{
  "name": "my-package",
  "changelog": {
    "types": {
      "feat": { "title": "Features" }
    },
    "repo": "user/my-package"
  }
}

Configuration Interface

interface ChangelogConfig {
  /** Working directory for git operations */
  cwd: string;
  
  /** Commit type configuration with titles and semver mapping */
  types: Record<string, { title: string; semver?: SemverBumpType } | boolean>;
  
  /** Scope name mapping for normalization */
  scopeMap: Record<string, string>;
  
  /** Repository configuration (auto-resolved if not provided) */
  repo?: RepoConfig | string;
  
  /** Authentication tokens for different providers */
  tokens: Partial<Record<RepoProvider, string>>;
  
  /** Starting commit reference */
  from: string;
  
  /** Ending commit reference */
  to: string;
  
  /** Target version for release */
  newVersion?: string;
  
  /** Whether git tags should be signed */
  signTags?: boolean;
  
  /** Output file path or false to disable file output */
  output: string | boolean;
  
  /** Publishing configuration */
  publish: {
    args?: string[];
    tag?: string;
    private?: boolean;
  };
  
  /** Template strings for commits and tags */
  templates: {
    commitMessage?: string;
    tagMessage?: string;
    tagBody?: string;
  };
  
  /** Disable author attribution section */
  noAuthors: boolean;
  
  /** Authors to exclude from attribution */
  excludeAuthors: string[];
  
  /** Hide author email addresses */
  hideAuthorEmail?: boolean;
}

Resolved Configuration

type ResolvedChangelogConfig = Omit<ChangelogConfig, "repo"> & {
  /** Fully resolved repository configuration */
  repo: RepoConfig;
};

Default Configuration

Changelogen provides comprehensive defaults that work out of the box:

Default Commit Types

const defaultTypes = {
  feat: { title: "🚀 Enhancements", semver: "minor" },
  perf: { title: "🔥 Performance", semver: "patch" },
  fix: { title: "🩹 Fixes", semver: "patch" },
  refactor: { title: "💅 Refactors", semver: "patch" },
  docs: { title: "📖 Documentation", semver: "patch" },
  build: { title: "📦 Build", semver: "patch" },
  types: { title: "🌊 Types", semver: "patch" },
  chore: { title: "🏡 Chore" },         // No semver bump
  examples: { title: "🏀 Examples" },   // No semver bump
  test: { title: "✅ Tests" },          // No semver bump
  style: { title: "🎨 Styles" },       // No semver bump
  ci: { title: "🤖 CI" }               // No semver bump
};

Default Templates

const defaultTemplates = {
  commitMessage: "chore(release): v{{newVersion}}",
  tagMessage: "v{{newVersion}}",
  tagBody: "v{{newVersion}}"
};

Default Publishing

const defaultPublish = {
  private: false,
  tag: "latest",
  args: []
};

Auto-Resolution Features

Repository Auto-Detection

Automatically detects repository information from:

package.json repository field:

{
  "repository": "user/repo",
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo.git"
  }
}

Git remote URL:
```
git remote get-url origin
```

Reference Auto-Resolution

from: Defaults to latest git tag (git describe --tags --abbrev=0)
to: Defaults to current git reference (HEAD)
output: Resolves relative paths to absolute paths

Token Auto-Resolution

Automatically resolves authentication tokens from:

Environment variables (GITHUB_TOKEN, GH_TOKEN, etc.)
Configuration files
GitHub CLI authentication

Environment Variables

GitHub Integration

# GitHub token (in order of precedence)
CHANGELOGEN_TOKENS_GITHUB=ghp_xxxxxxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
GH_TOKEN=ghp_xxxxxxxxxxxx

# NPM publishing
NPM_CONFIG_PROVENANCE=false  # Disable provenance in CI

Configuration Override

# Override configuration via environment
CHANGELOG_FROM=v1.0.0
CHANGELOG_TO=HEAD
CHANGELOG_OUTPUT=RELEASES.md

Advanced Configuration

Custom Commit Types

const config = await loadChangelogConfig(process.cwd(), {
  types: {
    // Custom types with emojis
    feature: { title: "✨ New Features", semver: "minor" },
    bugfix: { title: "🐛 Bug Fixes", semver: "patch" },
    security: { title: "🔒 Security", semver: "patch" },
    breaking: { title: "💥 Breaking Changes", semver: "major" },
    
    // Disable certain types
    chore: false,
    
    // Types without semver impact
    docs: { title: "📝 Documentation" }
  }
});

Scope Mapping

const config = await loadChangelogConfig(process.cwd(), {
  scopeMap: {
    // Normalize scope names
    "ui": "interface",
    "cli": "command-line",
    "db": "database",
    "api": "API",
    
    // Group related scopes
    "auth": "authentication",
    "oauth": "authentication"
  }
});

Author Filtering

const config = await loadChangelogConfig(process.cwd(), {
  // Exclude bots and automated commits
  excludeAuthors: [
    "dependabot[bot]",
    "renovate[bot]",
    "github-actions[bot]",
    "ci@company.com"
  ],
  
  // Hide email addresses for privacy
  hideAuthorEmail: true,
  
  // Disable author section entirely
  noAuthors: false
});

Custom Templates

const config = await loadChangelogConfig(process.cwd(), {
  templates: {
    // Custom commit message format
    commitMessage: "release: {{newVersion}}",
    
    // Custom tag formats
    tagMessage: "Release {{newVersion}}",
    tagBody: "Release {{newVersion}}\n\nSee CHANGELOG.md for details"
  }
});

Publishing Configuration

const config = await loadChangelogConfig(process.cwd(), {
  publish: {
    // Custom npm tag
    tag: "beta",
    
    // Additional npm publish arguments
    args: ["--access", "public", "--registry", "https://npm.example.com"],
    
    // Publish private packages
    private: true
  }
});

Configuration Validation

The configuration system includes built-in validation:

Required fields: Ensures essential configuration is present
Type checking: Validates configuration value types
Path resolution: Converts relative paths to absolute paths
Repository validation: Validates repository URL formats
Token validation: Checks token format and accessibility

Error Handling

Configuration loading handles various error conditions:

Missing configuration files: Uses defaults gracefully
Invalid JSON/YAML: Provides clear syntax error messages
Missing repository: Attempts auto-detection from git
Invalid paths: Resolves relative to working directory
Permission errors: Clear error messages for file access issues