pipecraft 0.0.0-releaseit → 0.26.0

package/src/utils/ast-path-operations.ts

@@ -1,581 +0,0 @@
-import { parseDocument, stringify, YAMLMap, YAMLSeq, Scalar, Node } from 'yaml'
-
-/**
- * # AST Path Operations for YAML Manipulation
- * 
- * This module provides a powerful and precise way to manipulate YAML documents using
- * path-based operations. It allows you to target specific locations in the YAML
- * structure and apply different types of operations (set, merge, overwrite, preserve).
- * 
- * ## Key Features
- * 
- * - **Path-based targeting**: Use dot notation to target specific YAML paths
- * - **Multiple operation types**: Set, merge, overwrite, or preserve values
- * - **Flexible value types**: Support objects, arrays, strings, YAML nodes, and parsed documents
- * - **Type safety**: Full TypeScript support with proper Node types
- * - **Context injection**: Dynamic values can be injected at build time
- * 
- * ## Usage Examples
- * 
- * ### Basic Path Operations
- * ```typescript
- * import { applyPathOperations, createValueFromString } from './ast-path-operations'
- * 
- * const operations = [
- *   {
- *     path: 'on.workflow_call.inputs.version',
- *     operation: 'set',
- *     value: {
- *       description: 'The version to deploy',
- *       required: false,
- *       type: 'string'
- *     }
- *   }
- * ]
- * 
- * applyPathOperations(doc, operations)
- * ```
- * 
- * ### Complex Job Definitions
- * ```typescript
- * const jobOperation = {
- *   path: 'jobs.changes',
- *   operation: 'overwrite',
- *   value: createValueFromString(`
- *     runs-on: ubuntu-latest
- *     steps:
- *       - uses: ./.github/actions/detect-changes
- *         with:
- *           baseRef: ${{ inputs.baseRef || 'main' }}
- *   `)
- * }
- * ```
- * 
- * ### Array Merging
- * ```typescript
- * const branchOperation = {
- *   path: 'on.pull_request.branches',
- *   operation: 'merge',
- *   value: ['develop', 'staging', 'main']
- * }
- * ```
- * 
- * ## Operation Types
- * 
- * - **`set`**: Set a value at the specified path (creates if doesn't exist)
- * - **`merge`**: Merge with existing value (for objects/arrays)
- * - **`overwrite`**: Replace existing value completely
- * - **`preserve`**: Keep existing value, ignore template value
- * 
- * ## Value Types Supported
- * 
- * - **Objects**: `{ key: 'value' }` - Simple key-value pairs
- * - **Arrays**: `['item1', 'item2']` - Simple arrays
- * - **YAML Strings**: Multi-line YAML with proper formatting
- * - **Parsed Documents**: Pre-parsed YAML nodes
- * - **Primitives**: strings, numbers, booleans
- * 
- * @fileoverview Path-based AST operations for precise YAML manipulation
- * @author Pipecraft Team
- * @version 1.0.0
- */
-
-/**
- * Available operation types for path-based AST manipulation
- * 
- * @typedef {('set' | 'merge' | 'overwrite' | 'preserve')} PathOperation
- * 
- * - `set`: Set a value at the specified path (creates if doesn't exist)
- * - `merge`: Merge with existing value (for objects/arrays)  
- * - `overwrite`: Replace existing value completely
- * - `preserve`: Keep existing value, ignore template value
- */
-export type PathOperation = 'set' | 'merge' | 'overwrite' | 'preserve'
-
-/**
- * Supported value types for path operations
- * 
- * @typedef {(Node | object | string | number | boolean | any[])} PathValue
- * 
- * Supports YAML nodes, JavaScript objects, primitives, and arrays
- */
-export type PathValue = Node | object | string | number | boolean | any[]
-
-/**
- * Configuration for a single path operation
- * 
- * @interface PathOperationConfig
- * @property {string} path - Dot-notation path to target (e.g., 'jobs.changes.steps')
- * @property {PathOperation} operation - Type of operation to perform
- * @property {PathValue} value - Value to set/merge/overwrite
- * @property {boolean} [required=true] - Whether the path must exist
- * 
- * @example
- * ```typescript
- * const config: PathOperationConfig = {
- *   path: 'on.workflow_call.inputs.version',
- *   operation: 'set',
- *   value: {
- *     description: 'The version to deploy',
- *     required: false,
- *     type: 'string'
- *   },
- *   required: true
- * }
- * ```
- */
-export interface PathOperationConfig {
-  path: string
-  operation: PathOperation
-  value: PathValue
-  required?: boolean
-  commentBefore?: string
-  comment?: string
-  spaceBefore?: boolean
-  spaceBeforeComment?: boolean
-  tag?: string
-}
-
-/**
- * Set a value at a specific path in the YAML AST
- * 
- * Creates intermediate nodes as needed and sets the final value at the specified path.
- * This is the core function for setting values in the YAML structure.
- * 
- * @param {YAMLMap} doc - The YAML document to modify
- * @param {string} path - Dot-notation path (e.g., 'jobs.changes.steps')
- * @param {PathValue} value - Value to set at the path
- * 
- * @throws {Error} When path navigation fails or parent is not a map
- * 
- * @example
- * ```typescript
- * const doc = parseDocument('name: Pipeline')
- * setPathValue(doc.contents, 'jobs.changes.runs-on', 'ubuntu-latest')
- * // Results in: jobs: { changes: { 'runs-on': 'ubuntu-latest' } }
- * ```
- */
-export function setPathValue(doc: YAMLMap, path: string, value: PathValue, document?: any, commentBefore?: string, spaceBeforeComment?: boolean): void {
-  const pathParts = path.split('.')
-  let current: Node = doc
-  
-  // Navigate to the parent of the target
-  for (let i = 0; i < pathParts.length - 1; i++) {
-    const part = pathParts[i]
-    
-    if (current instanceof YAMLMap) {
-      let next: any = current.get(part)
-      if (!next) {
-        // Create missing intermediate nodes
-        next = new YAMLMap()
-        current.set(part, next)
-      }
-      current = next
-    } else {
-      throw new Error(`Cannot navigate to ${part} - parent is not a map`)
-    }
-  }
-  
-  // Set the final value
-  const finalKey = pathParts[pathParts.length - 1]
-  if (current instanceof YAMLMap) {
-    let node: any
-    
-    // Check if value is already a node (from createValueFromString, etc.)
-    if (value && typeof value === 'object' && ('items' in value || 'type' in value)) {
-      // Value is already a node, use it directly
-      node = value
-    } else {
-      // Value is not a node, create one
-      node = document && document.createNode ? document.createNode(value) : createNode(value)
-    }
-
-    // When commentBefore is provided, or when setting a job key (which may need comments added later),
-    // we need to create a Scalar key instead of a string key.
-    // This is because YAML's set() method creates a plain string key by default,
-    // but comments can only be attached to Scalar objects.
-    const isJobKey = pathParts.length === 2 && pathParts[0] === 'jobs'
-
-    if (commentBefore || isJobKey) {
-      // Create a Scalar key (with or without comment)
-      const scalarKey = new Scalar(finalKey)
-
-      if (commentBefore) {
-        ;(scalarKey as any).commentBefore = commentBefore
-      }
-
-      // Add blank line before the comment if requested
-      if (spaceBeforeComment) {
-        ;(scalarKey as any).spaceBefore = true
-      }
-
-      // Add the pair to the map with a Scalar key
-      current.add({ key: scalarKey, value: node })
-    } else {
-      // Normal case: use the simple set() method which creates a string key
-      current.set(finalKey, node)
-    }
-  } else {
-    throw new Error(`Cannot set ${finalKey} - parent is not a map`)
-  }
-}
-
-/**
- * Get a value at a specific path in the YAML AST
- * 
- * Navigates to the specified path and returns the node if found, null otherwise.
- * This is useful for checking if a path exists before applying operations.
- * 
- * @param {YAMLMap} doc - The YAML document to read from
- * @param {string} path - Dot-notation path (e.g., 'jobs.changes.steps')
- * @returns {Node | null} The node at the path, or null if not found
- * 
- * @example
- * ```typescript
- * const doc = parseDocument('jobs: { changes: { runs-on: ubuntu-latest } }')
- * const value = getPathValue(doc.contents, 'jobs.changes.runs-on')
- * console.log(value) // Scalar('ubuntu-latest')
- * ```
- */
-export function getPathValue(doc: YAMLMap, path: string): Node | null {
-  const pathParts = path.split('.')
-  let current: Node = doc
-  
-  for (const part of pathParts) {
-    if (current instanceof YAMLMap) {
-      current = current.get(part) as Node
-      if (!current) return null
-    } else {
-      return null
-    }
-  }
-  
-  return current
-}
-
-/**
- * Ensure a path exists and apply the specified operation
- * 
- * This is the main orchestration function that handles all path operations.
- * It checks if the path exists, applies the appropriate operation based on
- * the configuration, and handles required vs optional paths.
- * 
- * @param {YAMLMap} doc - The YAML document to modify
- * @param {PathOperationConfig} config - Operation configuration
- * 
- * @example
- * ```typescript
- * const config: PathOperationConfig = {
- *   path: 'jobs.changes.runs-on',
- *   operation: 'set',
- *   value: 'ubuntu-latest',
- *   required: true
- * }
- * 
- * ensurePathAndApply(doc, config)
- * ```
- */
-export function ensurePathAndApply(
-  doc: YAMLMap,
-  config: PathOperationConfig,
-  document?: any
-): void {
-  const { path, operation, value, required = true, commentBefore, spaceBeforeComment } = config
-
-  // Check if path exists
-  const existingValue = getPathValue(doc, path)
-
-  if (!existingValue && !required) {
-    // Path doesn't exist and not required - skip
-    return
-  }
-
-  // Apply operation based on whether path exists or not
-  // For required paths that don't exist, we still respect the operation type
-  switch (operation) {
-    case 'set':
-      setPathValue(doc, path, value, document, commentBefore, spaceBeforeComment)
-      break
-
-    case 'merge':
-      // Merge will handle non-existent paths by creating them
-      mergePathValue(doc, path, value, document)
-      break
-
-    case 'overwrite':
-      setPathValue(doc, path, value, document, commentBefore, spaceBeforeComment)
-      break
-
-    case 'preserve':
-      // Only preserve if path exists, otherwise create it
-      if (!existingValue) {
-        setPathValue(doc, path, value, document, commentBefore, spaceBeforeComment)
-      }
-      // If exists, do nothing - keep existing value
-      break
-  }
-}
-
-/**
- * Merge a value at a specific path (for objects/arrays)
- * 
- * Intelligently merges values based on their type:
- * - Objects: Merges key-value pairs, preserving existing keys
- * - Arrays: Adds new items that don't already exist
- * - Other types: Falls back to overwrite behavior
- * 
- * @param {YAMLMap} doc - The YAML document to modify
- * @param {string} path - Dot-notation path to merge at
- * @param {PathValue} value - Value to merge
- * 
- * @example
- * ```typescript
- * // Merge object properties
- * mergePathValue(doc, 'on.workflow_call.inputs', {
- *   version: { description: 'Version to deploy' },
- *   environment: { description: 'Environment to deploy to' }
- * })
- * 
- * // Merge array items
- * mergePathValue(doc, 'on.pull_request.branches', ['feature-branch'])
- * ```
- */
-function mergePathValue(doc: YAMLMap, path: string, value: PathValue, document?: any): void {
-  const existingValue = getPathValue(doc, path)
-  
-  if (!existingValue) {
-    setPathValue(doc, path, value, document)
-    return
-  }
-  
-  // Merge logic based on type
-  if (existingValue instanceof YAMLMap && typeof value === 'object') {
-    // Merge objects
-    const newMap = (document && document.createNode ? document.createNode(value) : createNode(value)) as YAMLMap
-    for (const pair of newMap.items) {
-      const key = pair.key
-      const val = pair.value
-      existingValue.set(key, val)
-    }
-  } else if (existingValue instanceof YAMLSeq && Array.isArray(value)) {
-    // Merge arrays - add new items that don't exist
-    const newSeq = (document && document.createNode ? document.createNode(value) : createNode(value)) as YAMLSeq
-    for (const item of newSeq.items) {
-      if (!existingValue.items.some(existing => 
-        stringify(existing) === stringify(item)
-      )) {
-        existingValue.items.push(item)
-      }
-    }
-  } else {
-    // Fallback to overwrite
-    setPathValue(doc, path, value, document)
-  }
-}
-
-/**
- * Create a YAML node from a JavaScript value, YAML node, or parsed document
- * 
- * This is the core value conversion function that handles all supported value types.
- * It intelligently converts JavaScript values to appropriate YAML nodes.
- * 
- * @param {PathValue} value - Value to convert to YAML node
- * @returns {Node} The converted YAML node
- * 
- * @example
- * ```typescript
- * // Convert object
- * const node = createNode({ key: 'value' })
- * 
- * // Convert array
- * const node = createNode(['item1', 'item2'])
- * 
- * // Convert string
- * const node = createNode('simple string')
- * 
- * // Convert YAML string
- * const node = createNode(createValueFromString(`
- *   runs-on: ubuntu-latest
- *   steps:
- *     - name: Example step
- *       run: echo "Hello"
- * `))
- * ```
- */
-function createNode(value: PathValue): Node {
-  // If it's already a YAML node, return it
-  if (value && typeof value === 'object' && 'type' in value) {
-    return value as Node
-  }
-  
-  // If it's a parsed document, extract the contents
-  if (value && typeof value === 'object' && 'contents' in value) {
-    const contents = (value as any).contents
-    // If contents is a single item, return it directly
-    if (contents && typeof contents === 'object' && 'type' in contents) {
-      return contents
-    }
-    return contents
-  }
-  
-  // Handle primitive types
-  if (typeof value === 'string') {
-    return new Scalar(value)
-  } else if (typeof value === 'number') {
-    return new Scalar(value)
-  } else if (typeof value === 'boolean') {
-    return new Scalar(value)
-  } else if (Array.isArray(value)) {
-    const seq = new YAMLSeq()
-    for (const item of value) {
-      seq.items.push(createNode(item))
-    }
-    return seq
-  } else if (typeof value === 'object' && value !== null) {
-    const map = new YAMLMap()
-    for (const [key, val] of Object.entries(value)) {
-      map.set(key, createNode(val))
-    }
-    return map
-  } else {
-    return new Scalar(value)
-  }
-}
-
-/**
- * Apply multiple path operations to a document
- * 
- * This is the main entry point for applying multiple operations to a YAML document.
- * It processes all operations in order and applies them to the document.
- * 
- * @param {YAMLMap} doc - The YAML document to modify
- * @param {PathOperationConfig[]} operations - Array of operations to apply
- * 
- * @example
- * ```typescript
- * const operations: PathOperationConfig[] = [
- *   {
- *     path: 'on.workflow_call.inputs.version',
- *     operation: 'set',
- *     value: { description: 'Version to deploy', required: false, type: 'string' }
- *   },
- *   {
- *     path: 'jobs.changes',
- *     operation: 'overwrite',
- *     value: createValueFromString(`
- *       runs-on: ubuntu-latest
- *       steps:
- *         - uses: ./.github/actions/detect-changes
- *     `)
- *   }
- * ]
- * 
- * applyPathOperations(doc, operations)
- * ```
- */
-export function applyPathOperations(
-  doc: YAMLMap, 
-  operations: PathOperationConfig[],
-  document?: any
-): void {
-  for (const operation of operations) {
-    ensurePathAndApply(doc, operation, document)
-  }
-}
-
-/**
- * Helper functions for creating values
- * 
- * These convenience functions make it easier to create YAML nodes from different
- * value types. They handle the parsing and conversion automatically.
- */
-
-/**
- * Create a YAML node from a YAML string
- * 
- * Parses a YAML string and returns the root node. This is useful for complex
- * multi-line YAML structures like job definitions.
- * 
- * @param {string} yamlString - YAML string to parse
- * @returns {Node} The parsed YAML node
- * 
- * @example
- * ```typescript
- * const node = createValueFromString(`
- *   runs-on: ubuntu-latest
- *   steps:
- *     - name: Checkout code
- *       uses: actions/checkout@v3
- *     - name: Run tests
- *       run: npm test
- * `)
- * ```
- */
-export function createValueFromString(yamlString: string, context?: any, document?: any): Node {
-  // Evaluate JavaScript template literals in the string using the provided context
-  // Use a more sophisticated approach that handles nested braces
-  let processedString = yamlString
-  let match
-  const regex = /\$\{([^{}]+)\}/g
-  
-  while ((match = regex.exec(processedString)) !== null) {
-    const [fullMatch, expression] = match
-    try {
-      // Create a function that evaluates the expression with the context
-      const func = new Function('ctx', `return ${expression}`)
-      const result = func(context || {})
-      processedString = processedString.replace(fullMatch, JSON.stringify(result))
-      // Reset regex lastIndex to avoid issues with string replacement
-      regex.lastIndex = 0
-    } catch (error) {
-      // If evaluation fails, return the original expression as a string
-      processedString = processedString.replace(fullMatch, `"${expression}"`)
-      regex.lastIndex = 0
-    }
-  }
-  
-  // Parse the YAML string and return the root content as a proper Node
-  const doc = parseDocument(processedString)
-  return doc.contents as Node
-}
-
-/**
- * Create a YAML node from a JavaScript object
- * 
- * Converts a plain JavaScript object to a YAML map node.
- * 
- * @param {object} obj - JavaScript object to convert
- * @returns {Node} The converted YAML map node
- * 
- * @example
- * ```typescript
- * const node = createValueFromObject({
- *   description: 'The version to deploy',
- *   required: false,
- *   type: 'string'
- * })
- * ```
- */
-export function createValueFromObject(obj: object, doc?: any): Node {
-  if (doc && doc.createNode) {
-    return doc.createNode(obj)
-  }
-  return createNode(obj)
-}
-
-/**
- * Create a YAML node from a JavaScript array
- * 
- * Converts a JavaScript array to a YAML sequence node.
- * 
- * @param {any[]} arr - JavaScript array to convert
- * @returns {Node} The converted YAML sequence node
- * 
- * @example
- * ```typescript
- * const node = createValueFromArray(['develop', 'staging', 'main'])
- * ```
- */
-export function createValueFromArray(arr: any[]): Node {
-  return createNode(arr)
-}

package/src/utils/config.ts

@@ -1,64 +0,0 @@
-import { cosmiconfigSync } from 'cosmiconfig'
-import { PipecraftConfig, DomainConfig } from '../types/index.js'  
-
-export const loadConfig = (configPath?: string) => {
-  const explorer = cosmiconfigSync('pipecraft')
-  const result = configPath ? explorer.load(configPath) : explorer.search()
-  
-  if (!result) {
-    throw new Error(`No configuration file found. Expected: ${configPath || '.pipecraftrc.json'}`)
-  }
-  
-  return result.config
-}
-
-export const validateConfig = (config: any) => {
-  const requiredFields = ['ciProvider', 'mergeStrategy', 'requireConventionalCommits', 'initialBranch', 'finalBranch', 'branchFlow', 'domains']
-  
-  for (const field of requiredFields) {
-    if (!(field in config)) {
-      throw new Error(`Missing required field: ${field}`)
-    }
-  }
-  
-  if (!['github', 'gitlab'].includes(config.ciProvider)) {
-    throw new Error('ciProvider must be either "github" or "gitlab"')
-  }
-  
-  if (!['fast-forward', 'merge'].includes(config.mergeStrategy)) {
-    throw new Error('mergeStrategy must be either "fast-forward" or "merge"')
-  }
-  
-  if (!Array.isArray(config.branchFlow) || config.branchFlow.length < 2) {
-    throw new Error('branchFlow must be an array with at least 2 branches')
-  }
-  
-  if (typeof config.domains !== 'object') {
-    throw new Error('domains must be an object')
-  }
-  
-  for (const [domainName, domainConfig] of Object.entries(config.domains) as [string, DomainConfig][]) {
-    if (!domainConfig || typeof domainConfig !== 'object') {
-      throw new Error(`Domain "${domainName}" must be an object`)
-    }
-    
-    if (!domainConfig.paths || !Array.isArray(domainConfig.paths)) {
-      throw new Error(`Domain "${domainName}" must have a "paths" array`)
-    }
-    
-    if (domainConfig.paths.length === 0) {
-      throw new Error(`Domain "${domainName}" must have at least one path pattern`)
-    }
-    
-    // Set defaults for optional properties
-    if (domainConfig.testable === undefined) {
-      domainConfig.testable = true
-    }
-    if (domainConfig.deployable === undefined) {
-      domainConfig.deployable = true
-    }
-  }
-
-  
-  return true
-}