pipecraft 0.0.0-releaseit → 0.26.0

package/dist/utils/preflight.js

@@ -1,14 +1,45 @@
 /**
- * Pre-flight checks for PipeCraft commands
- * Validates environment and prerequisites before executing commands
+ * Pre-Flight Validation Checks
+ *
+ * This module implements comprehensive environment validation before workflow generation.
+ * Pre-flight checks prevent common failures by validating:
+ * - PipeCraft configuration exists and is valid
+ * - Git repository is properly initialized
+ * - Git remote is configured
+ * - Workflow directories are writable
+ * - Node.js version meets minimum requirements
+ *
+ * All checks return structured results with actionable error messages and suggestions.
+ * This provides a better user experience by catching issues early with clear guidance
+ * on how to resolve them.
+ *
+ * @module utils/preflight
  */
 import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { execSync } from 'child_process';
 import { join } from 'path';
 import { cosmiconfigSync } from 'cosmiconfig';
 /**
- * Check if config file exists using cosmiconfig
- * Searches for .pipecraftrc.json, .pipecraftrc, or package.json pipecraft key
+ * Check if PipeCraft configuration file exists.
+ *
+ * Uses cosmiconfig to search for configuration files in standard locations:
+ * - .pipecraftrc.json
+ * - .pipecraftrc (JSON or YAML)
+ * - pipecraft.config.js
+ * - package.json (pipecraft key)
+ *
+ * Searches current directory and all parent directories.
+ *
+ * @returns Check result with pass/fail status and file location if found
+ *
+ * @example
+ * ```typescript
+ * const result = checkConfigExists()
+ * if (!result.passed) {
+ *   console.error(result.message)
+ *   console.log(result.suggestion) // "Run 'pipecraft init' to create..."
+ * }
+ * ```
  */
 export function checkConfigExists() {
     const explorer = cosmiconfigSync('pipecraft');
@@ -26,7 +57,26 @@ export function checkConfigExists() {
     };
 }
 /**
- * Check if config file is valid and has required fields
+ * Check if configuration file is valid and contains required fields.
+ *
+ * Validates:
+ * - File can be parsed (valid JSON/YAML)
+ * - Required fields are present (ciProvider, branchFlow, domains)
+ * - At least one domain is configured
+ *
+ * @returns Check result with validation status and specific error if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = checkConfigValid()
+ * if (!result.passed) {
+ *   if (result.message.includes('missing required fields')) {
+ *     // Config exists but incomplete
+ *   } else if (result.message.includes('Invalid JSON')) {
+ *     // Syntax error in config file
+ *   }
+ * }
+ * ```
  */
 export function checkConfigValid() {
     const explorer = cosmiconfigSync('pipecraft');
@@ -79,12 +129,31 @@ export function checkConfigValid() {
     }
 }
 /**
- * Check if current directory is a git repository
+ * Check if current directory is inside a git repository.
+ *
+ * PipeCraft requires a git repository to:
+ * - Generate GitHub Actions workflows
+ * - Track version history
+ * - Enable version management features
+ *
+ * Uses `git rev-parse --is-inside-work-tree` to detect git repository.
+ * Suppresses stderr to avoid noise when git is not initialized.
+ *
+ * @returns Check result indicating if directory is in a git repository
+ *
+ * @example
+ * ```typescript
+ * const result = checkInGitRepo()
+ * if (!result.passed) {
+ *   console.log('Please initialize git first')
+ *   execSync('git init')
+ * }
+ * ```
  */
 export function checkInGitRepo() {
     try {
         execSync('git rev-parse --is-inside-work-tree', {
-            stdio: 'pipe',
+            stdio: ['pipe', 'pipe', 'ignore'], // Suppress stderr to avoid "not a git repository" errors
             encoding: 'utf8'
         });
         return {
@@ -101,12 +170,35 @@ export function checkInGitRepo() {
     }
 }
 /**
- * Check if git remote is configured
+ * Check if git remote named 'origin' is configured.
+ *
+ * A git remote is required for:
+ * - Pushing generated workflows to GitHub
+ * - Repository information extraction
+ * - GitHub API integration
+ *
+ * Checks specifically for the 'origin' remote, which is the standard
+ * default remote name. Also detects if the remote is GitHub vs. GitLab
+ * and provides appropriate messaging.
+ *
+ * @returns Check result with remote URL if configured
+ *
+ * @example
+ * ```typescript
+ * const result = checkHasGitRemote()
+ * if (!result.passed) {
+ *   console.log('No git remote found')
+ *   execSync('git remote add origin https://github.com/user/repo.git')
+ * } else if (result.suggestion) {
+ *   // GitLab detected - show warning about experimental support
+ *   console.warn(result.suggestion)
+ * }
+ * ```
  */
 export function checkHasGitRemote() {
     try {
         const remote = execSync('git remote get-url origin', {
-            stdio: 'pipe',
+            stdio: ['pipe', 'pipe', 'ignore'], // Suppress stderr
             encoding: 'utf8'
         }).trim();
         if (!remote) {
@@ -135,7 +227,29 @@ export function checkHasGitRemote() {
     }
 }
 /**
- * Check if .github directory is writable
+ * Check if .github/workflows directory exists and is writable.
+ *
+ * Workflows are written to .github/workflows/, so this directory must:
+ * - Exist or be creatable
+ * - Be writable by the current user
+ *
+ * This check attempts to:
+ * 1. Create .github/workflows/ if it doesn't exist
+ * 2. Write a test file to verify write permissions
+ * 3. Clean up the test file
+ *
+ * @returns Check result indicating if directory is writable
+ *
+ * @example
+ * ```typescript
+ * const result = checkCanWriteGithubDir()
+ * if (!result.passed) {
+ *   if (result.message.includes('permission')) {
+ *     // Fix permissions
+ *     execSync('chmod +w .github/workflows/')
+ *   }
+ * }
+ * ```
  */
 export function checkCanWriteGithubDir() {
     const githubDir = '.github';
@@ -178,7 +292,28 @@ export function checkCanWriteGithubDir() {
     }
 }
 /**
- * Check Node.js version
+ * Check if Node.js version meets minimum requirement.
+ *
+ * PipeCraft requires Node.js 18.0.0 or higher because it uses:
+ * - Modern ES modules
+ * - Latest TypeScript features
+ * - Current GitHub Actions syntax
+ *
+ * Only checks major version for simplicity. Minor/patch versions
+ * within the same major release are considered compatible.
+ *
+ * @param minVersion - Minimum required version (default: '18.0.0')
+ * @returns Check result with current and minimum versions
+ *
+ * @example
+ * ```typescript
+ * const result = checkNodeVersion('18.0.0')
+ * if (!result.passed) {
+ *   console.error('Please upgrade Node.js')
+ *   console.log('Current:', process.version)
+ *   console.log('Required: >= 18.0.0')
+ * }
+ * ```
  */
 export function checkNodeVersion(minVersion = '18.0.0') {
     const currentVersion = process.version.slice(1); // Remove 'v' prefix
@@ -197,8 +332,38 @@ export function checkNodeVersion(minVersion = '18.0.0') {
     };
 }
 /**
- * Run all pre-flight checks for generate command
- * Note: No longer needs configPath - uses cosmiconfig to search automatically
+ * Run all pre-flight checks for workflow generation.
+ *
+ * Executes comprehensive environment validation to ensure all prerequisites
+ * are met before attempting to generate workflows. This prevents partial
+ * failures and provides clear error messages upfront.
+ *
+ * Checks performed:
+ * - Configuration file exists
+ * - Configuration is valid
+ * - Inside git repository
+ * - Git remote configured
+ * - Workflow directory writable
+ *
+ * Note: Node version check is optional and not included by default since
+ * if Node is too old, the code wouldn't run at all.
+ *
+ * @returns Collection of all check results
+ *
+ * @example
+ * ```typescript
+ * const checks = runPreflightChecks()
+ * const { allPassed, output } = formatPreflightResults(checks)
+ *
+ * if (!allPassed) {
+ *   console.error('Pre-flight checks failed:')
+ *   console.log(output)
+ *   process.exit(1)
+ * }
+ *
+ * // Proceed with workflow generation
+ * await generateWorkflows()
+ * ```
  */
 export function runPreflightChecks() {
     return {
@@ -210,7 +375,33 @@ export function runPreflightChecks() {
     };
 }
 /**
- * Format preflight results for display
+ * Format pre-flight check results for human-readable display.
+ *
+ * Converts structured check results into formatted output with:
+ * - ✅/❌ icons for visual scanning
+ * - Error messages and suggestions
+ * - Next steps if all checks passed
+ * - Helpful guidance for getting started
+ *
+ * The output is designed to be printed directly to the console.
+ *
+ * @param checks - Collection of check results from runPreflightChecks()
+ * @returns Formatted output object with overall status and display string
+ *
+ * @example
+ * ```typescript
+ * const checks = runPreflightChecks()
+ * const { allPassed, output, nextSteps } = formatPreflightResults(checks)
+ *
+ * console.log(output)
+ *
+ * if (allPassed && nextSteps) {
+ *   console.log('\n' + nextSteps.join('\n'))
+ * } else {
+ *   console.error('\n⚠ Fix the above issues and try again')
+ *   process.exit(1)
+ * }
+ * ```
  */
 export function formatPreflightResults(checks) {
     const results = [];
@@ -244,12 +435,21 @@ export function formatPreflightResults(checks) {
     };
 }
 /**
- * Get current git branch name
+ * Get current git branch name.
+ *
+ * Uses `git branch --show-current` to get the active branch.
+ * Falls back to 'main' if:
+ * - Not in a git repository
+ * - In detached HEAD state
+ * - Git command fails
+ *
+ * @returns Current branch name or 'main' as fallback
+ * @private
  */
 function getCurrentBranch() {
     try {
         const branch = execSync('git branch --show-current', {
-            stdio: 'pipe',
+            stdio: ['pipe', 'pipe', 'ignore'], // Suppress stderr
             encoding: 'utf8'
         }).trim();
         return branch || 'main';

package/dist/utils/preflight.js.map

@@ -1 +1 @@
-{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../src/utils/preflight.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../src/utils/preflight.ts"],"names":[],"mappings":"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"}

package/dist/utils/versioning.d.ts

@@ -1,37 +1,189 @@
+/**
+ * Version Management and Semantic Versioning Utilities
+ *
+ * This module provides comprehensive version management using release-it and
+ * conventional commits. It handles:
+ * - Automatic version calculation based on commit history
+ * - Generation of release-it, commitlint, and husky configurations
+ * - Git tag creation and management
+ * - Conventional commit validation
+ * - Changelog generation
+ *
+ * The VersionManager integrates with the trunk-based workflow to automatically
+ * bump versions when code is promoted through the pipeline.
+ *
+ * @module utils/versioning
+ */
 import { PipecraftConfig } from '../types/index.js';
+/**
+ * Manager for semantic versioning and release automation.
+ *
+ * This class handles all version-related operations including configuration
+ * generation, version calculation, and commit validation. It integrates with
+ * release-it for automated versioning and conventional-changelog for
+ * changelog generation.
+ *
+ * @example
+ * ```typescript
+ * const versionManager = new VersionManager(config)
+ *
+ * // Setup version management (creates config files)
+ * versionManager.setupVersionManagement()
+ *
+ * // Get current version from git tags
+ * const currentVersion = versionManager.getCurrentVersion()
+ *
+ * // Calculate next version based on commits
+ * const { version, type } = versionManager.calculateNextVersion()
+ * console.log(`Next version: ${version} (${type} bump)`)
+ * ```
+ */
 export declare class VersionManager {
     private config;
+    /**
+     * Create a new VersionManager instance.
+     *
+     * @param config - PipeCraft configuration object
+     */
     constructor(config: PipecraftConfig);
     /**
-     * Generate release-it configuration
+     * Generate release-it configuration file content.
+     *
+     * Creates a CommonJS module exporting release-it configuration that:
+     * - Disables npm publishing (for monorepos/private packages)
+     * - Configures git tagging with conventional versioning
+     * - Sets up conventional-changelog plugin for automatic version bumping
+     * - Merges user-defined bump rules with sensible defaults
+     *
+     * The generated config uses a custom whatBump function that analyzes
+     * conventional commits to determine the appropriate version bump level
+     * (major, minor, or patch).
+     *
+     * @returns JavaScript module string ready to write to .release-it.cjs
+     *
+     * @example
+     * ```typescript
+     * const config = versionManager.generateReleaseItConfig()
+     * writeFileSync('.release-it.cjs', config)
+     * ```
      */
     generateReleaseItConfig(): string;
     /**
-     * Generate commitlint configuration
+     * Generate commitlint configuration file content.
+     *
+     * Creates a CommonJS module that configures commitlint to enforce
+     * conventional commit message format. This ensures all commits follow
+     * a consistent structure that can be parsed for automatic versioning.
+     *
+     * Enforced rules include:
+     * - Valid commit types (feat, fix, docs, etc.)
+     * - Lowercase types
+     * - Non-empty subjects
+     * - Lowercase subject (except proper nouns)
+     * - No trailing period in subject
+     *
+     * @returns JavaScript module string ready to write to commitlint.config.js
      */
     generateCommitlintConfig(): string;
     /**
-     * Generate husky configuration
+     * Generate husky commit-msg hook script.
+     *
+     * Creates a shell script that runs commitlint on every commit message.
+     * This hook automatically validates commit messages before they're accepted,
+     * preventing non-conventional commits from entering the repository.
+     *
+     * @returns Shell script string ready to write to .husky/commit-msg
      */
     generateHuskyConfig(): string;
     /**
-     * Setup version management files
+     * Setup version management infrastructure.
+     *
+     * Creates all necessary configuration files and hooks for automated
+     * version management:
+     * - .release-it.cjs (release-it configuration)
+     * - commitlint.config.js (commit message linting)
+     * - .husky/commit-msg (git hook for commit validation)
+     * - package.json scripts (release, changelog commands)
+     *
+     * Only runs if versioning is enabled in configuration.
+     * Installs husky if not already present.
+     *
+     * @example
+     * ```typescript
+     * versionManager.setupVersionManagement()
+     * // Files created:
+     * // - .release-it.cjs
+     * // - commitlint.config.js
+     * // - .husky/commit-msg
+     * // - Updated package.json
+     * ```
      */
     setupVersionManagement(): void;
     /**
-     * Update package.json with version management scripts
+     * Update package.json with version management scripts.
+     *
+     * Adds npm scripts for common version management tasks:
+     * - release: Run release-it to create a new version
+     * - release:dry: Preview what release-it would do
+     * - version:check: Check what version would be bumped to
+     * - changelog: Generate CHANGELOG.md from commits
+     * - commit: Stage and commit with interactive prompting
+     * - prepare: Install husky hooks (runs automatically on npm install)
+     *
+     * @private
      */
     private updatePackageJsonScripts;
     /**
-     * Check if conventional commits are being used
+     * Validate that recent commits follow conventional commit format.
+     *
+     * Checks the last 10 commits to determine if the repository is following
+     * conventional commit conventions. This can be used as a pre-flight check
+     * before enabling versioning features.
+     *
+     * Expected format: `type(scope?): subject`
+     * Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+     *
+     * @returns true if all recent commits follow conventional format
+     *
+     * @example
+     * ```typescript
+     * if (!versionManager.validateConventionalCommits()) {
+     *   console.warn('⚠ Some commits do not follow conventional format')
+     *   console.log('Enable with: git config commit.template .gitmessage')
+     * }
+     * ```
      */
     validateConventionalCommits(): boolean;
     /**
-     * Get current version from git tags
+     * Get the current version from git tags.
+     *
+     * Finds the most recent git tag matching semantic versioning format (v*.*.*)
+     * and returns it as a version string. Strips the leading 'v' if present.
+     *
+     * @returns Current version string (e.g., "1.2.3") or "0.0.0" if no tags exist
+     *
+     * @example
+     * ```typescript
+     * const currentVersion = versionManager.getCurrentVersion()
+     * console.log(`Current version: v${currentVersion}`)
+     * ```
      */
     getCurrentVersion(): string;
     /**
-     * Calculate next version based on conventional commits
+     * Calculate the next version based on conventional commits.
+     *
+     * Runs release-it in dry-run mode to determine what version would be
+     * created based on commits since the last tag. Analyzes conventional
+     * commit messages to determine the appropriate bump level.
+     *
+     * @returns Object containing the next version string and bump type
+     *
+     * @example
+     * ```typescript
+     * const { version, type } = versionManager.calculateNextVersion()
+     * console.log(`Next ${type} version: ${version}`)
+     * // Output: "Next minor version: 1.3.0"
+     * ```
      */
     calculateNextVersion(): {
         version: string;

package/dist/utils/versioning.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../../src/utils/versioning.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEnD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,eAAe;IAInC;;OAEG;IACH,uBAAuB,IAAI,MAAM;IAuEjC;;OAEG;IACH,wBAAwB,IAAI,MAAM;IA8BlC;;OAEG;IACH,mBAAmB,IAAI,MAAM;IAO7B;;OAEG;IACH,sBAAsB,IAAI,IAAI;IAgC9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqBhC;;OAEG;IACH,2BAA2B,IAAI,OAAO;IActC;;OAEG;IACH,iBAAiB,IAAI,MAAM;IAS3B;;OAEG;IACH,oBAAoB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;CAuB1D"}
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../../src/utils/versioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAiB;IAE/B;;;;OAIG;gBACS,MAAM,EAAE,eAAe;IAInC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uBAAuB,IAAI,MAAM;IAuEjC;;;;;;;;;;;;;;;OAeG;IACH,wBAAwB,IAAI,MAAM;IA8BlC;;;;;;;;OAQG;IACH,mBAAmB,IAAI,MAAM;IAO7B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,sBAAsB,IAAI,IAAI;IAkC9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,wBAAwB;IAsBhC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,2BAA2B,IAAI,OAAO;IAkBtC;;;;;;;;;;;;;OAaG;IACH,iBAAiB,IAAI,MAAM;IAa3B;;;;;;;;;;;;;;;OAeG;IACH,oBAAoB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;CAwB1D"}