@0xsequence/catapult 1.4.0 → 1.5.0

package/src/lib/parsers/job.ts

@@ -1,160 +0,0 @@
-import { parse as parseYaml, YAMLParseError } from 'yaml'
-import { Condition, Job, JobAction } from '../types'
-
-/**
- * Determines whether a raw YAML item is a valid Condition.
- * Mirrors the validation logic used for templates so job-level
- * skip conditions behave consistently.
- */
-function isCondition(item: any): item is Condition {
-  if (!item || typeof item !== 'object' || typeof item.type !== 'string') {
-    return false
-  }
-
-  if (['contract-exists', 'job-completed'].includes(item.type)) {
-    return true
-  }
-
-  if (item.type === 'basic-arithmetic') {
-    const op = item.arguments?.operation
-    return typeof op === 'string' && ['eq', 'neq', 'gt', 'lt', 'gte', 'lte'].includes(op)
-  }
-
-  return false
-}
-
-/**
- * Parses a YAML string defining a job into a structured `Job` object.
- * This function validates the presence and basic types of required fields
- * for both the job and its nested actions.
- *
- * @param yamlContent The raw YAML content of the job file as a string.
- * @returns The parsed and validated `Job` object.
- * @throws {Error} If the YAML is malformed or if the job is missing required fields.
- */
-export function parseJob(yamlContent: string): Job {
-  let rawObject: any
-  try {
-    rawObject = parseYaml(yamlContent)
-  } catch (e) {
-    if (e instanceof YAMLParseError) {
-      const line = e.linePos?.[0].line ? ` at line ${e.linePos[0].line}` : ''
-      throw new Error(`Failed to parse job YAML: ${e.message}${line}.`)
-    }
-    throw e
-  }
-
-  if (!rawObject || typeof rawObject !== 'object') {
-    throw new Error('Invalid job: YAML content must resolve to an object.')
-  }
-
-  // If a top-level discriminator exists and is not a job, bail out early with a helpful error
-  if (rawObject.type && rawObject.type !== 'job') {
-    throw new Error('Invalid job: unexpected type discriminator. Did you mean a template file with type: "template"?')
-  }
-
-  // --- Validate required top-level fields ---
-  if (!rawObject.name || typeof rawObject.name !== 'string') {
-    throw new Error('Invalid job: "name" field is required and must be a string.')
-  }
-  // The YAML parser may interpret a version like "1.0" as a number, so we ensure it's a string.
-  if (!rawObject.version) {
-    throw new Error(`Invalid job "${rawObject.name}": "version" field is required.`)
-  }
-  rawObject.version = String(rawObject.version)
-
-  if (!rawObject.actions || !Array.isArray(rawObject.actions)) {
-    throw new Error(`Invalid job "${rawObject.name}": "actions" field is required and must be an array.`)
-  }
-
-  // --- Validate each action within the job ---
-  for (const action of rawObject.actions) {
-    if (!action || typeof action !== 'object') {
-      throw new Error(`Invalid job "${rawObject.name}": contains a non-object item in "actions" array.`)
-    }
-    if (!action.name || typeof action.name !== 'string') {
-      throw new Error(`Invalid job "${rawObject.name}": an action is missing the required "name" field.`)
-    }
-    
-    // Validate that the action has either a template or type field, but not both
-    const hasTemplate = action.template && typeof action.template === 'string'
-    const hasType = action.type && typeof action.type === 'string'
-    
-    if (!hasTemplate && !hasType) {
-      throw new Error(`Invalid job "${rawObject.name}": action "${action.name}" must have either a "template" field (for template actions) or a "type" field (for primitive actions).`)
-    }
-    if (hasTemplate && hasType) {
-      throw new Error(`Invalid job "${rawObject.name}": action "${action.name}" cannot have both "template" and "type" fields. Use only one.`)
-    }
-    
-    if (!action.arguments || typeof action.arguments !== 'object' || Array.isArray(action.arguments)) {
-      throw new Error(`Invalid job "${rawObject.name}": action "${action.name}" is missing the required "arguments" field or it is not an object.`)
-    }
-    
-    // Validate the optional output field
-    if (action.output !== undefined) {
-      const t = typeof action.output
-      const isObject = t === 'object' && action.output !== null && !Array.isArray(action.output)
-      if (t !== 'boolean' && !isObject) {
-        throw new Error(`Invalid job "${rawObject.name}": action "${action.name}" has an invalid "output" field. It must be either a boolean (true/false) or an object mapping custom outputs.`)
-      }
-    }
-  }
-
-  // --- Optional: validate deprecated flag if present ---
-  if (rawObject.deprecated !== undefined && typeof rawObject.deprecated !== 'boolean') {
-    throw new Error(`Invalid job "${rawObject.name}": "deprecated" must be a boolean if provided.`)
-  }
-  // --- Optional: validate min_evm_version if present ---
-  if (rawObject.min_evm_version !== undefined && typeof rawObject.min_evm_version !== 'string') {
-    throw new Error(`Invalid job "${rawObject.name}": "min_evm_version" must be a string if provided.`)
-  }
-
-  // --- Optional: validate job-level skip_condition and skip_if ---
-  if (rawObject.skip_condition !== undefined) {
-    if (!Array.isArray(rawObject.skip_condition)) {
-      throw new Error(`Invalid job "${rawObject.name}": "skip_condition" must be an array if provided.`)
-    }
-    for (const condition of rawObject.skip_condition) {
-      if (!isCondition(condition)) {
-        throw new Error(`Invalid job "${rawObject.name}": "skip_condition" contains an invalid condition entry.`)
-      }
-    }
-  }
-
-  if (rawObject.skip_if !== undefined) {
-    if (!Array.isArray(rawObject.skip_if)) {
-      throw new Error(`Invalid job "${rawObject.name}": "skip_if" must be an array if provided.`)
-    }
-    for (const condition of rawObject.skip_if) {
-      if (!isCondition(condition)) {
-        throw new Error(`Invalid job "${rawObject.name}": "skip_if" contains an invalid condition entry.`)
-      }
-    }
-  }
-
-  if (rawObject.constants !== undefined) {
-    if (typeof rawObject.constants !== 'object' || rawObject.constants === null || Array.isArray(rawObject.constants)) {
-      throw new Error(`Invalid job "${rawObject.name}": "constants" field must be an object if provided.`)
-    }
-  }
-
-  // --- Construct and return the strongly-typed Job object ---
-  const job: Job = {
-    name: rawObject.name,
-    version: rawObject.version,
-    description: rawObject.description,
-    depends_on: rawObject.depends_on,
-    // We've validated the necessary parts, so a cast is reasonable here.
-    actions: rawObject.actions as JobAction[],
-    only_networks: rawObject.only_networks,
-    skip_networks: rawObject.skip_networks,
-    min_evm_version: rawObject.min_evm_version,
-    deprecated: rawObject.deprecated === true,
-    skip_condition: rawObject.skip_condition as Condition[] | undefined,
-    skip_if: rawObject.skip_if as Condition[] | undefined,
-    constants: rawObject.constants,
-  }
-
-  return job
-}

package/src/lib/parsers/source.ts

@@ -1,129 +0,0 @@
-import { parse as parseYaml, YAMLParseError } from 'yaml'
-import { BuildInfoSourceProvenance, SourceDocument, SourceProvenance, SourceProvenanceOverride } from '../types'
-
-const STRING_FIELDS = ['repo', 'ref', 'commit', 'build'] as const
-const BUILD_INFO_FIELDS = new Set<string>([...STRING_FIELDS, 'contracts'])
-const CONTRACT_OVERRIDE_FIELDS = new Set<string>(STRING_FIELDS)
-
-function isPlainObject(value: any): value is Record<string, any> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function buildInfoLabel(buildInfoPath: string): string {
-  return `build_info[${JSON.stringify(buildInfoPath)}]`
-}
-
-function contractOverrideLabel(buildInfoPath: string, contractName: string): string {
-  return `${buildInfoLabel(buildInfoPath)}.contracts[${JSON.stringify(contractName)}]`
-}
-
-function validateKnownFields(value: Record<string, any>, label: string, allowedFields: Set<string>): void {
-  for (const field of Object.keys(value)) {
-    if (!allowedFields.has(field)) {
-      throw new Error(`Invalid source: ${label}.${field} is not supported.`)
-    }
-  }
-}
-
-function validateStringFields(value: Record<string, any>, label: string, requiredRepo: boolean): void {
-  if (requiredRepo && (typeof value.repo !== 'string' || value.repo.length === 0)) {
-    throw new Error(`Invalid source: ${label}.repo field is required and must be a non-empty string.`)
-  }
-
-  for (const field of STRING_FIELDS) {
-    if (value[field] !== undefined && typeof value[field] !== 'string') {
-      throw new Error(`Invalid source: ${label}.${field} must be a string if provided.`)
-    }
-  }
-}
-
-function validateBuildInfoProvenance(buildInfoPath: string, provenance: unknown): BuildInfoSourceProvenance {
-  if (!isPlainObject(provenance)) {
-    throw new Error(`Invalid source: ${buildInfoLabel(buildInfoPath)} must be an object.`)
-  }
-
-  const label = buildInfoLabel(buildInfoPath)
-  validateKnownFields(provenance, label, BUILD_INFO_FIELDS)
-  validateStringFields(provenance, label, true)
-
-  if (provenance.contracts !== undefined) {
-    if (!isPlainObject(provenance.contracts)) {
-      throw new Error(`Invalid source: ${label}.contracts must be an object if provided.`)
-    }
-
-    for (const [contractName, override] of Object.entries(provenance.contracts)) {
-      if (!contractName || typeof contractName !== 'string') {
-        throw new Error(`Invalid source: ${label}.contracts keys must be non-empty strings.`)
-      }
-      if (!isPlainObject(override)) {
-        throw new Error(`Invalid source: ${contractOverrideLabel(buildInfoPath, contractName)} must be an object.`)
-      }
-      const overrideLabel = contractOverrideLabel(buildInfoPath, contractName)
-      validateKnownFields(override, overrideLabel, CONTRACT_OVERRIDE_FIELDS)
-      validateStringFields(override, overrideLabel, false)
-    }
-  }
-
-  return provenance as BuildInfoSourceProvenance
-}
-
-/**
- * Parses a YAML source provenance document.
- * Returns null for YAML documents that are not marked with `type: "source"`.
- */
-export function parseSourceDocument(yamlContent: string): SourceDocument | null {
-  let rawObject: any
-  try {
-    rawObject = parseYaml(yamlContent)
-  } catch (e) {
-    if (e instanceof YAMLParseError) {
-      const line = (e as any).linePos?.[0]?.line ? ` at line ${(e as any).linePos[0].line}` : ''
-      throw new Error(`Failed to parse source YAML: ${e.message}${line}.`)
-    }
-    throw e
-  }
-
-  if (!rawObject || typeof rawObject !== 'object') {
-    return null
-  }
-
-  if (rawObject.type !== 'source') {
-    return null
-  }
-
-  if (!isPlainObject(rawObject.build_info)) {
-    throw new Error('Invalid source: "build_info" field is required and must be an object.')
-  }
-
-  const buildInfo: Record<string, BuildInfoSourceProvenance> = {}
-  const warnings: string[] = []
-
-  for (const [buildInfoPath, provenance] of Object.entries(rawObject.build_info)) {
-    if (!buildInfoPath || typeof buildInfoPath !== 'string') {
-      throw new Error('Invalid source: "build_info" keys must be non-empty strings.')
-    }
-
-    try {
-      buildInfo[buildInfoPath] = validateBuildInfoProvenance(buildInfoPath, provenance)
-    } catch (error) {
-      warnings.push(error instanceof Error ? error.message : String(error))
-    }
-  }
-
-  return {
-    type: 'source',
-    build_info: buildInfo,
-    warnings
-  }
-}
-
-export function mergeSourceProvenance(
-  base: BuildInfoSourceProvenance,
-  override?: SourceProvenanceOverride
-): SourceProvenance {
-  const { contracts, ...baseFields } = base
-  return {
-    ...baseFields,
-    ...(override || {})
-  }
-}

package/src/lib/parsers/template.ts

@@ -1,135 +0,0 @@
-import { parse as parseYaml, YAMLParseError } from 'yaml'
-import { Template, Action, Condition, Value } from '../types'
-
-/**
- * Helper to check if a parsed YAML object represents a Condition.
- * Conditions are specific checks that resolve to a boolean, used in `skip_condition` blocks.
- * @param item The parsed object from YAML.
- * @returns True if the item is a Condition, false otherwise.
- */
-function isCondition(item: any): item is Condition {
-  // A 'Condition' must be an object with a 'type' property.
-  if (!item || typeof item !== 'object' || typeof item.type !== 'string') {
-    return false
-  }
-
-  // Check against known, specific condition types from `src/lib/types/conditions.ts`.
-  if (['contract-exists', 'job-completed'].includes(item.type)) {
-    return true
-  }
-
-  if (item.type === 'value-empty') {
-    return !!(item.arguments && typeof item.arguments === 'object' && 'value' in item.arguments)
-  }
-
-  // The 'basic-arithmetic' ValueResolver can also act as a Condition
-  // if it performs a boolean comparison operation.
-  if (item.type === 'basic-arithmetic') {
-    if (item.arguments && typeof item.arguments.operation === 'string') {
-      const booleanOperations = ['eq', 'neq', 'gt', 'lt', 'gte', 'lte']
-      return booleanOperations.includes(item.arguments.operation)
-    }
-  }
-
-  return false
-}
-
-/**
- * Parses a YAML string defining an action template into a structured `Template` object.
- * This function handles validation and normalization of the template structure, including
- * the flexible `setup` block which can be an array of mixed actions/conditions or
- * a structured object.
- *
- * @param yamlContent The raw YAML content of the template file as a string.
- * @returns The parsed and validated `Template` object.
- * @throws {Error} If the YAML is malformed, or if the template is missing required fields
- *                 like `name`, `actions`, or `outputs`.
- */
-export function parseTemplate(yamlContent: string): Template {
-  let rawObject: any
-  try {
-    rawObject = parseYaml(yamlContent)
-  } catch (e) {
-    if (e instanceof YAMLParseError) {
-      // Provide a more user-friendly error message including the line number
-      const line = e.linePos?.[0].line ? ` at line ${e.linePos[0].line}` : ''
-      throw new Error(`Failed to parse template YAML: ${e.message}${line}.`)
-    }
-    throw e
-  }
-
-  if (!rawObject || typeof rawObject !== 'object') {
-    throw new Error('Invalid template: YAML content must resolve to an object.')
-  }
-
-  // If a discriminator is provided, ensure it matches
-  if (rawObject.type !== undefined && rawObject.type !== 'template') {
-    throw new Error('Invalid template: expected type to be "template" if provided.')
-  }
-
-  // --- Validate required fields ---
-  if (!rawObject.name || typeof rawObject.name !== 'string') {
-    throw new Error('Invalid template: "name" field is required and must be a string.')
-  }
-  if (!rawObject.actions || !Array.isArray(rawObject.actions)) {
-    throw new Error(`Invalid template "${rawObject.name}": "actions" field is required and must be an array.`)
-  }
-  
-  // Allow 'outputs' to be optional. If it exists, it must be an object.
-  if (rawObject.outputs && (typeof rawObject.outputs !== 'object' || Array.isArray(rawObject.outputs))) {
-    throw new Error(`Invalid template "${rawObject.name}": "outputs" field must be an object if provided.`)
-  }
-
-  // --- Construct the base template object ---
-  const template: Template = {
-    type: 'template',
-    name: rawObject.name,
-    description: rawObject.description,
-    arguments: rawObject.arguments,
-    returns: rawObject.returns,
-    actions: rawObject.actions as Action[],
-    skip_condition: rawObject.skip_condition as Condition[],
-  }
-
-  // Only include outputs if it was provided in the YAML
-  if (rawObject.outputs) {
-    template.outputs = rawObject.outputs as Record<string, Value<any>>
-  }
-
-  // --- Handle the 'setup' block which can have multiple formats ---
-  if (rawObject.setup) {
-    if (Array.isArray(rawObject.setup)) {
-      // Format 1: An array of mixed actions and conditions (e.g., sequence-factory-v1.yaml).
-      // We need to iterate and categorize each item.
-      const setupActions: Action[] = []
-      const setupConditions: Condition[] = []
-
-      for (const item of rawObject.setup) {
-        if (isCondition(item)) {
-          setupConditions.push(item)
-        } else {
-          // If it's not an explicit condition, we assume it's an action.
-          setupActions.push(item as Action)
-        }
-      }
-
-      template.setup = {}
-      if (setupActions.length > 0) {
-        template.setup.actions = setupActions
-      }
-      if (setupConditions.length > 0) {
-        template.setup.skip_condition = setupConditions
-      }
-    } else if (typeof rawObject.setup === 'object') {
-      // Format 2: A structured object (e.g., nano-universal-deployer.yaml), which maps directly to our type.
-      template.setup = {
-        actions: (rawObject.setup.actions || []) as Action[],
-        skip_condition: (rawObject.setup.skip_condition || []) as Condition[],
-      }
-    } else {
-      throw new Error(`Invalid template "${rawObject.name}": "setup" field must be an array or an object if provided.`)
-    }
-  }
-
-  return template
-}