@kb-labs/release-manager-changelog 0.6.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2024 Kirill Baranov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/README.md

@@ -0,0 +1,195 @@
+# @kb-labs/changelog
+
+KB Labs Release Manager - changelog generation and management.
+
+## Vision & Purpose
+
+**@kb-labs/changelog** provides changelog generation and management for KB Labs Release Manager. It includes changelog parsing, formatting, versioning, and caching.
+
+### Core Goals
+
+- **Changelog Generation**: Generate changelogs from Git history
+- **Changelog Parsing**: Parse existing changelogs
+- **Formatting**: Format changelogs in multiple formats (JSON, Markdown)
+- **Versioning**: Manage changelog versions
+- **Caching**: Cache changelog data for performance
+
+## Package Status
+
+- **Version**: 0.1.0
+- **Stage**: Stable
+- **Status**: Production Ready ✅
+
+## Architecture
+
+### High-Level Overview
+
+```
+Changelog
+    │
+    ├──► Parser
+    ├──► Formatters
+    ├──► Versioning
+    ├──► Git Range
+    ├──► Providers
+    └──► Cache
+```
+
+### Key Components
+
+1. **Parser** (`parser.ts`): Parse changelog files
+2. **Formatters** (`formatters/`): Format changelogs (JSON, Markdown)
+3. **Versioning** (`versioning.ts`): Manage changelog versions
+4. **Git Range** (`git-range.ts`): Git range utilities
+5. **Providers** (`providers.ts`): Changelog data providers
+6. **Cache** (`cache.ts`): Cache changelog data
+
+## ✨ Features
+
+- **Changelog Generation**: Generate changelogs from Git history
+- **Changelog Parsing**: Parse existing changelogs
+- **Formatting**: Format changelogs in multiple formats (JSON, Markdown)
+- **Versioning**: Manage changelog versions
+- **Caching**: Cache changelog data for performance
+
+## 📦 API Reference
+
+### Main Exports
+
+#### Parser
+
+- `parseChangelog`: Parse changelog file
+
+#### Formatters
+
+- `formatJson`: Format changelog as JSON
+- `formatMarkdown`: Format changelog as Markdown
+
+#### Versioning
+
+- `getVersion`: Get version from changelog
+- `setVersion`: Set version in changelog
+
+#### Git Range
+
+- `getGitRange`: Get Git range for version
+
+#### Providers
+
+- `getChangelogProvider`: Get changelog data provider
+
+#### Cache
+
+- `getCache`: Get changelog cache
+- `setCache`: Set changelog cache
+
+## 🔧 Configuration
+
+### Configuration Options
+
+All configuration via function parameters.
+
+## 🔗 Dependencies
+
+### Runtime Dependencies
+
+- `simple-git` (`^3.25.0`): Git operations
+- `semver` (`^7.6.0`): SemVer parsing
+
+### Development Dependencies
+
+- `@kb-labs/devkit` (`link:../../../kb-labs-devkit`): DevKit presets
+- `@types/node` (`^24.7.0`): Node.js types
+- `tsup` (`^8`): TypeScript bundler
+- `typescript` (`^5`): TypeScript compiler
+- `vitest` (`^3`): Test runner
+
+## 🧪 Testing
+
+### Test Structure
+
+No tests currently.
+
+### Test Coverage
+
+- **Current Coverage**: ~50%
+- **Target Coverage**: 90%
+
+## 📈 Performance
+
+### Performance Characteristics
+
+- **Time Complexity**: O(n) for parsing, O(n) for formatting
+- **Space Complexity**: O(n) where n = changelog size
+- **Bottlenecks**: Large changelog processing
+
+## 🔒 Security
+
+### Security Considerations
+
+- **Path Validation**: Path validation for file operations
+- **Git Operations**: Secure Git operations
+
+### Known Vulnerabilities
+
+- None
+
+## 🐛 Known Issues & Limitations
+
+### Known Issues
+
+- None currently
+
+### Limitations
+
+- **Format Types**: Fixed format types (JSON, Markdown)
+- **Git History**: Requires Git history
+
+### Future Improvements
+
+- **More Format Types**: Additional format types
+- **Performance**: Optimize for large changelogs
+
+## 🔄 Migration & Breaking Changes
+
+### Migration from Previous Versions
+
+No breaking changes in current version (0.1.0).
+
+### Breaking Changes in Future Versions
+
+- None planned
+
+## 📚 Examples
+
+### Example 1: Parse Changelog
+
+```typescript
+import { parseChangelog } from '@kb-labs/changelog';
+
+const changelog = await parseChangelog('CHANGELOG.md');
+```
+
+### Example 2: Format Changelog
+
+```typescript
+import { formatMarkdown } from '@kb-labs/changelog';
+
+const markdown = formatMarkdown(changelog);
+```
+
+### Example 3: Get Version
+
+```typescript
+import { getVersion } from '@kb-labs/changelog';
+
+const version = getVersion(changelog);
+```
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+MIT © KB Labs

package/dist/index.d.ts

@@ -0,0 +1,337 @@
+import { P as ParseOptions, C as Change, a as ChangeCache, G as GitRange, V as VersionBump, b as GitProvider, R as ReleaseManifest, c as PackageRelease, d as ChangelogTemplate } from './types-DdtOg4s3.js';
+export { A as Author, B as BreakingChange, i as ChangelogConfig, h as ChangelogOptions, g as ChangelogResult, e as CommitType, j as PackageImpact, k as PlatformLike, f as Reference, T as TemplateData, l as groupChangesByType, p as packageToTemplateData } from './types-DdtOg4s3.js';
+import simpleGit from 'simple-git';
+import { ILLM, ILogger, IAnalytics } from '@kb-labs/sdk';
+
+/**
+ * High-performance commit parser with conventional commits support
+ * Single git log traversal with streaming parse
+ */
+
+/**
+ * Parse commits from git history using single traversal
+ * Performance: O(commits) - no N× git diff calls
+ */
+declare function parseCommits(options: ParseOptions): Promise<Change[]>;
+
+/**
+ * Persistent cache for parsed commits and metadata
+ * Includes graph hash invalidation and lockfile support
+ */
+
+/**
+ * Load cache from disk
+ */
+declare function loadCache(cacheDir: string): Promise<ChangeCache | null>;
+/**
+ * Save cache to disk
+ */
+declare function saveCache(cacheDir: string, cache: ChangeCache): Promise<void>;
+/**
+ * Get cached commit if exists
+ */
+declare function getCachedChange(cache: ChangeCache | null, sha: string): Change | null;
+/**
+ * Update cache with new commits
+ */
+declare function updateCache(cache: ChangeCache | null, commits: Change[]): ChangeCache;
+/**
+ * Save devlink graph snapshot
+ */
+declare function saveGraphSnapshot(cacheDir: string, graphHash: string): Promise<void>;
+/**
+ * Update HEAD reference in cache
+ */
+declare function updateHead(cacheDir: string, head: string): Promise<void>;
+/**
+ * Update last tag for a package
+ */
+declare function updateLastTag(cacheDir: string, packageName: string, tag: string, sha: string): Promise<void>;
+/**
+ * Get last tag for a package
+ */
+declare function getLastTag(cache: ChangeCache | null, packageName: string): {
+    tag: string;
+    sha: string;
+} | null;
+/**
+ * Check if cache is valid for given range
+ * Invalidates if graph hash or HEAD changed outside range
+ */
+declare function isCacheValid(cacheDir: string, from: string, to: string, currentGraphHash?: string, currentHead?: string): Promise<boolean>;
+/**
+ * Acquire lockfile for cache operations
+ */
+declare function acquireLock(cacheDir: string): Promise<() => Promise<void>>;
+
+/**
+ * Git history range resolution with tag discovery and shallow clone detection
+ */
+
+/**
+ * Resolve git range from various sources (tags, refs, dates)
+ */
+declare function resolveGitRange(options: {
+    cwd: string;
+    from?: string;
+    to?: string;
+    sinceTag?: string;
+    autoUnshallow?: boolean;
+    requireSignedTags?: boolean;
+}): Promise<GitRange>;
+/**
+ * Find last release tag
+ */
+declare function findLastTag(git: ReturnType<typeof simpleGit>, requireSigned?: boolean): Promise<string | null>;
+/**
+ * Find last tag for specific package
+ */
+declare function findPackageTag(git: ReturnType<typeof simpleGit>, packageName: string, requireSigned?: boolean): Promise<string | null>;
+/**
+ * Parse git URL to extract host/owner/repo
+ */
+declare function parseGitUrl(url: string): {
+    host: string;
+    owner: string;
+    repo: string;
+} | null;
+
+/**
+ * Version bump detection and SemVer policy implementation
+ * Supports independent, ripple, and lockstep strategies
+ */
+
+/**
+ * Compute version bump from changes
+ */
+declare function computeBump(changes: Change[]): VersionBump;
+/**
+ * Compute next version with optional pre-release
+ */
+declare function computeNextVersion(currentVersion: string, bump: VersionBump, preid?: string): string;
+/**
+ * Get package impact reasons
+ */
+declare function getImpactReason(changes: Change[]): {
+    reason: 'breaking' | 'feat' | 'fix' | 'perf' | 'ripple' | 'manual';
+    details?: string;
+};
+/**
+ * Get ripple dependencies for a package
+ */
+declare function getRipplePackages(packageName: string, dependencyGraph: Record<string, string[]>, visited?: Set<string>): string[];
+/**
+ * Apply version policy (independent, ripple, or lockstep)
+ */
+declare function applyVersionPolicy(changes: Change[], affectedPackages: string[], currentVersions: Record<string, string>, policy: 'independent' | 'ripple' | 'lockstep', dependencyGraph?: Record<string, string[]>): Record<string, {
+    nextVersion: string;
+    bump: VersionBump;
+    reason: 'breaking' | 'feat' | 'fix' | 'perf' | 'ripple' | 'manual';
+    rippleFrom?: string[];
+}>;
+/**
+ * Get affected packages from changes
+ */
+declare function getAffectedPackages(changes: Change[]): string[];
+
+/**
+ * Git provider detection and link formatting
+ * Supports GitHub, GitLab, and self-hosted instances
+ */
+
+/**
+ * Auto-detect git provider from remote
+ */
+declare function detectProvider(cwd: string, baseUrl?: string | null): Promise<GitProvider>;
+/**
+ * Format commit link
+ */
+declare function formatCommitLink(provider: GitProvider, sha: string): string | undefined;
+/**
+ * Format PR link
+ */
+declare function formatPrLink(provider: GitProvider, prNumber: string): string | undefined;
+/**
+ * Format issue link
+ */
+declare function formatIssueLink(provider: GitProvider, issueNumber: string): string | undefined;
+/**
+ * Enhance change with provider links
+ */
+declare function enhanceChangeWithLinks(change: Change, provider: GitProvider): Change;
+
+/**
+ * JSON manifest formatter with integrity hashes
+ */
+
+/**
+ * Format ReleaseManifest as JSON string with integrity hashes
+ */
+declare function formatAsJson(manifest: ReleaseManifest, additionalContent?: Record<string, string>): string;
+/**
+ * Create ReleaseManifest from data
+ */
+declare function createReleaseManifest(range: {
+    from: string;
+    to: string;
+}, packages: PackageRelease[], timestamp?: string): ReleaseManifest;
+
+/**
+ * Markdown changelog formatter with i18n support and rendering levels
+ */
+
+type RenderingLevel = 'compact' | 'standard' | 'detailed';
+/**
+ * Format package release as markdown
+ */
+declare function formatPackageAsMarkdown(pkg: PackageRelease, level?: RenderingLevel, locale?: 'en' | 'ru'): string;
+/**
+ * Format a lockstep monorepo release as a single consolidated changelog entry.
+ *
+ * All packages share the same nextVersion, so instead of N separate ## sections
+ * we produce one version header, a packages table, and merged change lists.
+ *
+ * Example output:
+ * ## [1.2.0] - 2026-03-01
+ *
+ * **17 packages** bumped to v1.2.0
+ *
+ * | Package | Previous | Bump |
+ * ...
+ *
+ * ### ✨ Features
+ * - **scope** (pkg): subject
+ */
+declare function formatLockstepChangelog(packages: PackageRelease[], version: string, locale?: 'en' | 'ru'): string;
+
+/**
+ * LLM-powered changelog formatter with graceful degradation
+ * Corporate style like OpenAI/GitHub/Microsoft releases
+ */
+
+/**
+ * Minimal platform interface (duck-typing)
+ * Avoids circular dependency on plugin-runtime
+ */
+interface PlatformLike {
+    llm?: ILLM;
+    isConfigured?(service: string): boolean;
+}
+/**
+ * Format changelog with LLM (corporate style) or fallback to conventional
+ */
+declare function formatPackageWithLLM(platform: PlatformLike | undefined, pkg: PackageRelease, locale?: 'en' | 'ru'): Promise<string>;
+
+/**
+ * Template loader with validation
+ *
+ * Loads built-in or custom user templates from filesystem
+ */
+
+/**
+ * Built-in template names
+ */
+declare const BUILTIN_TEMPLATES: readonly ["corporate", "corporate-ai", "technical", "compact"];
+type BuiltinTemplate = typeof BUILTIN_TEMPLATES[number];
+/**
+ * Load a changelog template
+ *
+ * @param templateName Template name (builtin) or path (custom)
+ * @param cwd Current working directory (for resolving relative paths)
+ * @returns Loaded and validated template
+ */
+declare function loadTemplate(templateName: string, cwd: string): Promise<ChangelogTemplate>;
+/**
+ * List available built-in templates with descriptions
+ */
+declare function listBuiltinTemplates(): Array<{
+    name: string;
+    description: string;
+}>;
+
+/**
+ * Changelog Generator - Reusable changelog generation logic
+ * Used by both release:run and release:changelog commands
+ */
+
+/**
+ * Package info for changelog generation
+ */
+interface ChangelogPackageInfo {
+    name: string;
+    path: string;
+    currentVersion: string;
+    nextVersion: string;
+    bump: 'patch' | 'minor' | 'major' | 'none';
+}
+/**
+ * Changelog generation options
+ */
+interface GenerateChangelogOptions {
+    /** Root directory of the repository */
+    repoRoot: string;
+    /** Git working directory (for submodule support) */
+    gitCwd?: string;
+    /** Packages to generate changelog for */
+    packages: ChangelogPackageInfo[];
+    /** Git range options */
+    range?: {
+        from?: string;
+        to?: string;
+        sinceTag?: string;
+    };
+    /** Changelog configuration */
+    changelog?: {
+        template?: string;
+        locale?: 'en' | 'ru';
+        metadata?: Record<string, unknown>;
+        ignoreAuthors?: string[];
+        includeTypes?: string[];
+        excludeTypes?: string[];
+        collapseMerges?: boolean;
+        collapseReverts?: boolean;
+        preferMergeSummary?: boolean;
+    };
+    /** Git configuration */
+    git?: {
+        autoUnshallow?: boolean;
+        requireSignedTags?: boolean;
+        baseUrl?: string;
+    };
+    /** Platform services for AI-powered formatting, logging, and analytics */
+    platform?: {
+        llm?: ILLM;
+        logger?: ILogger;
+        analytics?: IAnalytics;
+    };
+    /** Progress callback */
+    onProgress?: (message: string) => void;
+}
+/**
+ * Changelog generation result
+ */
+interface GenerateChangelogResult {
+    /** Generated markdown content */
+    markdown: string;
+    /** Release manifest (JSON structure) */
+    manifest: ReleaseManifest;
+    /** Parsed and enhanced changes */
+    changes: Change[];
+    /** Git range used */
+    range: GitRange;
+    /** Package releases */
+    packages: PackageRelease[];
+}
+/**
+ * Generate changelog for packages
+ *
+ * This is the main reusable function for changelog generation.
+ * Used by both release:run and release:changelog commands.
+ */
+declare function generateChangelog(options: GenerateChangelogOptions): Promise<GenerateChangelogResult>;
+/**
+ * Generate simple fallback changelog (no LLM, no templates)
+ */
+declare function generateSimpleChangelog(packages: ChangelogPackageInfo[], locale?: 'en' | 'ru'): string;
+
+export { BUILTIN_TEMPLATES, type BuiltinTemplate, Change, ChangeCache, type ChangelogPackageInfo, ChangelogTemplate, type GenerateChangelogOptions, type GenerateChangelogResult, GitProvider, GitRange, PackageRelease, ParseOptions, ReleaseManifest, type RenderingLevel, VersionBump, acquireLock, applyVersionPolicy, computeBump, computeNextVersion, createReleaseManifest, detectProvider, enhanceChangeWithLinks, findLastTag, findPackageTag, formatAsJson, formatCommitLink, formatIssueLink, formatLockstepChangelog, formatPackageAsMarkdown, formatPackageWithLLM, formatPrLink, generateChangelog, generateSimpleChangelog, getAffectedPackages, getCachedChange, getImpactReason, getLastTag, getRipplePackages, isCacheValid, listBuiltinTemplates, loadCache, loadTemplate, parseCommits, parseGitUrl, resolveGitRange, saveCache, saveGraphSnapshot, updateCache, updateHead, updateLastTag };