@0xsequence/catapult 1.3.16 → 1.4.0

package/src/lib/deployer.ts

@@ -261,13 +261,37 @@ export class Deployer {
             }
 
             // Check job-level skip conditions before execution
-            if (job.skip_condition) {
-              const shouldSkip = await engine.evaluateSkipConditions(job.skip_condition, context, new Map())
+            // skip_if is a pure gate (no post-check), skip_condition has both pre-skip and post-check
+            const skipIfConditions = job.skip_if
+            const skipConditions = job.skip_condition
+            
+            if (skipIfConditions || skipConditions) {
+              // Evaluate skip_if first (pure gate)
+              let shouldSkip = false
+              let skipReason: string = 'skip_condition'
+              
+              if (skipIfConditions) {
+                const skipIfResult = await engine.evaluateSkipConditions(skipIfConditions, context, new Map())
+                if (skipIfResult) {
+                  shouldSkip = true
+                  skipReason = 'skip_if'
+                }
+              }
+              
+              // If not skipped by skip_if, check skip_condition
+              if (!shouldSkip && skipConditions) {
+                const skipConditionResult = await engine.evaluateSkipConditions(skipConditions, context, new Map())
+                if (skipConditionResult) {
+                  shouldSkip = true
+                  skipReason = 'skip_condition'
+                }
+              }
+              
               if (shouldSkip) {
                 // Store skipped result
                 this.results.get(job.name)!.outputs.set(network.chainId, {
                   status: 'skipped',
-                  data: `Job "${job.name}" skipped due to skip condition`
+                  data: `Job "${job.name}" skipped due to ${skipReason}`
                 })
 
                 this.events.emitEvent({
@@ -276,7 +300,7 @@ export class Deployer {
                   data: {
                     jobName: job.name,
                     networkName: network.name,
-                    reason: 'skip_condition'
+                    reason: skipReason
                   }
                 })
 

package/src/lib/index.ts

@@ -10,5 +10,8 @@ export * as parsers from './parsers'
 // Export the deployer
 export * from './deployer'
 
+// Export provenance helpers
+export * from './provenance'
+
 // This will be the main entry point for the lib
-// Additional functionality will be added here as the lib grows
+// Additional functionality will be added here as the lib grows

package/src/lib/parsers/__tests__/job.spec.ts

@@ -355,4 +355,85 @@ actions:
       arguments: { address: '0xabc' }
     })
   })
+
+  it('should parse job-level skip_if conditions', () => {
+    const yamlContent = `
+name: "job-with-skip-if"
+version: "1"
+skip_if:
+  - type: "contract-exists"
+    arguments:
+      address: "0xdef"
+actions:
+  - name: "a1"
+    template: "t1"
+    arguments: {}
+`
+    const job = parseJob(yamlContent)
+    expect(job.skip_if).toHaveLength(1)
+    expect(job.skip_if?.[0]).toEqual({
+      type: 'contract-exists',
+      arguments: { address: '0xdef' }
+    })
+  })
+
+  it('should parse both skip_condition and skip_if on a job', () => {
+    const yamlContent = `
+name: "job-with-both"
+version: "1"
+skip_condition:
+  - type: "contract-exists"
+    arguments:
+      address: "0xabc"
+skip_if:
+  - type: "job-completed"
+    arguments:
+      job: "other-job"
+actions:
+  - name: "a1"
+    template: "t1"
+    arguments: {}
+`
+    const job = parseJob(yamlContent)
+    expect(job.skip_condition).toHaveLength(1)
+    expect(job.skip_condition?.[0]).toEqual({
+      type: 'contract-exists',
+      arguments: { address: '0xabc' }
+    })
+    expect(job.skip_if).toHaveLength(1)
+    expect(job.skip_if?.[0]).toEqual({
+      type: 'job-completed',
+      arguments: { job: 'other-job' }
+    })
+  })
+
+  it('should throw when skip_if is not an array', () => {
+    const yamlContent = `
+name: "job-with-invalid-skip-if"
+version: "1"
+skip_if:
+  type: "contract-exists"
+  arguments:
+    address: "0xabc"
+actions:
+  - name: "a1"
+    template: "t1"
+    arguments: {}
+`
+    expect(() => parseJob(yamlContent)).toThrow('"skip_if" must be an array if provided')
+  })
+
+  it('should throw when skip_if contains invalid condition', () => {
+    const yamlContent = `
+name: "job-with-invalid-skip-if"
+version: "1"
+skip_if:
+  - type: "invalid-type"
+actions:
+  - name: "a1"
+    template: "t1"
+    arguments: {}
+`
+    expect(() => parseJob(yamlContent)).toThrow('"skip_if" contains an invalid condition entry')
+  })
 })

package/src/lib/parsers/__tests__/source.spec.ts

@@ -0,0 +1,134 @@
+import { mergeSourceProvenance, parseSourceDocument } from '../source'
+
+describe('Source Provenance Parsing', () => {
+  it('should return null for non-source YAML documents', () => {
+    const result = parseSourceDocument(`
+type: constants
+constants:
+  value: 1
+`)
+
+    expect(result).toBeNull()
+  })
+
+  it('should parse source provenance documents', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+    ref: "v3.0.0-rc.5"
+    commit: "0d9061f229da73edae890e6fdd1fbf753028df6d"
+    build: "forge build --build-info"
+    contracts:
+      "src/Stage1Module.sol:Stage1Module":
+        ref: "stage1-special"
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.build_info['./stage1.json'].repo).toBe('https://github.com/0xsequence/wallet-contracts-v3')
+    expect(result!.build_info['./stage1.json'].contracts?.['src/Stage1Module.sol:Stage1Module'].ref).toBe('stage1-special')
+  })
+
+  it('should require repo on each build-info provenance entry', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    ref: "v3.0.0-rc.5"
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.build_info).toEqual({})
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('build_info["./stage1.json"].repo')
+    ])
+  })
+
+  it('should validate optional string fields', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+    commit: 123
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.build_info).toEqual({})
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('commit')
+    ])
+  })
+
+  it('should reject unsupported fields', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+    path: "contracts"
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.build_info).toEqual({})
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('path is not supported')
+    ])
+  })
+
+  it('should quote build-info paths in validation errors', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    ref: "v3.0.0-rc.5"
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('build_info["./stage1.json"].repo')
+    ])
+  })
+
+  it('should keep valid entries when sibling entries are invalid', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+  "./bad.json":
+    typo_field: true
+`)
+
+    expect(result).not.toBeNull()
+    expect(Object.keys(result!.build_info)).toEqual(['./stage1.json'])
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('typo_field is not supported')
+    ])
+  })
+
+  describe('mergeSourceProvenance', () => {
+    it('should merge contract overrides into build-info provenance', () => {
+      const result = mergeSourceProvenance({
+        repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+        ref: 'v3.0.0-rc.5',
+        commit: '0d9061f229da73edae890e6fdd1fbf753028df6d',
+        contracts: {
+          'src/Stage1Module.sol:Stage1Module': {
+            ref: 'stage1-special'
+          }
+        }
+      }, {
+        ref: 'stage1-special'
+      })
+
+      expect(result).toEqual({
+        repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+        ref: 'stage1-special',
+        commit: '0d9061f229da73edae890e6fdd1fbf753028df6d'
+      })
+      expect(result).not.toHaveProperty('contracts')
+    })
+  })
+})

package/src/lib/parsers/index.ts

@@ -3,3 +3,4 @@ export * from './template'
 export * from './job'
 export * from './buildinfo'
 export * from './constants'
+export * from './source'

package/src/lib/parsers/job.ts

@@ -110,7 +110,7 @@ export function parseJob(yamlContent: string): Job {
     throw new Error(`Invalid job "${rawObject.name}": "min_evm_version" must be a string if provided.`)
   }
 
-  // --- Optional: validate job-level skip_condition and constants ---
+  // --- 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.`)
@@ -122,6 +122,17 @@ export function parseJob(yamlContent: string): Job {
     }
   }
 
+  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.`)
@@ -141,8 +152,9 @@ export function parseJob(yamlContent: string): Job {
     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

@@ -0,0 +1,129 @@
+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 || {})
+  }
+}