@0xsequence/catapult 1.3.16 → 1.4.0

package/src/lib/contracts/__tests__/repository.spec.ts

@@ -1,7 +1,64 @@
 import * as fs from 'fs/promises'
 import * as path from 'path'
 import { ContractRepository } from '../repository'
-import { Contract } from '../../types/contracts'
+
+function buildInfoContent(): string {
+  return JSON.stringify({
+    _format: 'hh-sol-build-info-1',
+    id: 'test-build-id',
+    solcVersion: '0.8.0',
+    solcLongVersion: '0.8.0+commit.c7dfd78e',
+    input: {
+      language: 'Solidity',
+      sources: {
+        'src/Stage1Module.sol': {
+          content: 'contract Stage1Module {}'
+        },
+        'src/Stage2Module.sol': {
+          content: 'contract Stage2Module {}'
+        }
+      },
+      settings: {
+        outputSelection: {
+          '*': {
+            '*': ['abi', 'evm.bytecode', 'evm.deployedBytecode']
+          }
+        }
+      }
+    },
+    output: {
+      contracts: {
+        'src/Stage1Module.sol': {
+          Stage1Module: {
+            abi: [],
+            evm: {
+              bytecode: {
+                object: '0x608060405234801561001057600080fd5b50111111'
+              },
+              deployedBytecode: {
+                object: '0x608060405234801561001057600080fd5b50111112'
+              }
+            }
+          }
+        },
+        'src/Stage2Module.sol': {
+          Stage2Module: {
+            abi: [],
+            evm: {
+              bytecode: {
+                object: '0x608060405234801561001057600080fd5b50222222'
+              },
+              deployedBytecode: {
+                object: '0x608060405234801561001057600080fd5b50222223'
+              }
+            }
+          }
+        }
+      },
+      sources: {}
+    }
+  })
+}
 
 describe('ContractRepository', () => {
   let repository: ContractRepository
@@ -111,6 +168,217 @@ describe('ContractRepository', () => {
       expect(contract._sources.has(buildInfoPath)).toBe(true)
     })
 
+    it('should attach source provenance from build-info sidecars', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const sourcePath = path.join(buildInfoDir, 'source.yaml')
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(sourcePath, `
+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"
+`)
+
+      await repository.loadFrom(tempDir)
+
+      const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+      const stage2 = repository.lookup(`${buildInfoPath}:Stage2Module`)
+
+      expect(stage1).not.toBeNull()
+      expect(stage2).not.toBeNull()
+
+      expect(stage1!.sourceProvenance).toMatchObject({
+        repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+        ref: 'stage1-special',
+        commit: '0d9061f229da73edae890e6fdd1fbf753028df6d',
+        build: 'forge build --build-info',
+        sourceDocumentPath: sourcePath,
+        buildInfoPath
+      })
+      expect(stage2!.sourceProvenance).toMatchObject({
+        repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+        ref: 'v3.0.0-rc.5',
+        commit: '0d9061f229da73edae890e6fdd1fbf753028df6d'
+      })
+
+      expect(stage1!._sourceProvenance?.get(buildInfoPath)?.ref).toBe('stage1-special')
+    })
+
+    it('should skip source sidecars that point to missing build-info files', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./missing.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+`)
+
+      try {
+        await expect(repository.loadFrom(tempDir)).resolves.toBeUndefined()
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('does not exist'))
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
+
+    it('should skip malformed source sidecars without blocking build-info loading', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    ref: "v3.0.0-rc.5"
+`)
+
+      try {
+        await repository.loadFrom(tempDir)
+      } finally {
+        warnSpy.mockRestore()
+      }
+
+      const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+      expect(stage1).not.toBeNull()
+      expect(stage1!.sourceProvenance).toBeUndefined()
+    })
+
+    it('should keep valid source sidecar entries when sibling entries are invalid', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+    commit: "0d9061f229da73edae890e6fdd1fbf753028df6d"
+  "./bad.json":
+    typo_field: true
+`)
+
+      try {
+        await repository.loadFrom(tempDir)
+
+        const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+        expect(stage1).not.toBeNull()
+        expect(stage1!.sourceProvenance).toMatchObject({
+          repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+          commit: '0d9061f229da73edae890e6fdd1fbf753028df6d'
+        })
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('typo_field is not supported'))
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
+
+    it('should skip source sidecar entries that do not point to build-info JSON', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.txt":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+`)
+
+      try {
+        await repository.loadFrom(tempDir)
+
+        const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+        expect(stage1).not.toBeNull()
+        expect(stage1!.sourceProvenance).toBeUndefined()
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('does not point to a build-info JSON file'))
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
+
+    it('should skip duplicate source provenance entries for the same build-info file', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3-a"
+`)
+      await fs.writeFile(path.join(buildInfoDir, 'source.yml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3-b"
+`)
+
+      try {
+        await repository.loadFrom(tempDir)
+
+        const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+        expect(stage1).not.toBeNull()
+        expect(stage1!._sourceProvenance?.size).toBe(1)
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('duplicate provenance'))
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
+
+    it('should select preferred source provenance deterministically for duplicate bytecode', async () => {
+      const olderBuildInfoDir = path.join(tempDir, 'build-info', 'b-release')
+      const newerBuildInfoDir = path.join(tempDir, 'build-info', 'a-release')
+      await fs.mkdir(olderBuildInfoDir, { recursive: true })
+      await fs.mkdir(newerBuildInfoDir, { recursive: true })
+
+      const olderBuildInfoPath = path.join(olderBuildInfoDir, 'stage1.json')
+      const newerBuildInfoPath = path.join(newerBuildInfoDir, 'stage1.json')
+      await fs.writeFile(olderBuildInfoPath, buildInfoContent())
+      await fs.writeFile(newerBuildInfoPath, buildInfoContent())
+
+      await fs.writeFile(path.join(olderBuildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3-old"
+`)
+      await fs.writeFile(path.join(newerBuildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3-new"
+`)
+
+      await repository.loadFrom(tempDir)
+
+      const stage1 = repository.lookup(`${newerBuildInfoPath}:Stage1Module`)
+      expect(stage1).not.toBeNull()
+      expect(stage1!._sourceProvenance?.size).toBe(2)
+      expect(stage1!.sourceProvenance?.repo).toBe('https://github.com/0xsequence/wallet-contracts-v3-new')
+    })
+
     it('should hydrate contracts from multiple source files', async () => {
       // Create a basic artifact file (minimal info, will be hydrated by build-info)
       const artifactContent = JSON.stringify({
@@ -341,4 +609,4 @@ describe('ContractRepository', () => {
       expect(contracts).toHaveLength(0)
     })
   })
-})
+})

package/src/lib/contracts/repository.ts

@@ -2,23 +2,26 @@ import * as fs from 'fs/promises'
 import * as path from 'path'
 import { createHash } from 'crypto'
 import { Contract } from '../types/contracts'
+import { BuildInfoSourceProvenance, SourceProvenance } from '../types/source'
 import { parseArtifact } from '../parsers/artifact'
 import { parseBuildInfo, isBuildInfoFile } from '../parsers/buildinfo'
+import { mergeSourceProvenance, parseSourceDocument } from '../parsers/source'
 
 export class ContractRepository {
   private contracts: Map<string, Contract> = new Map()
   private referenceMap: Map<string, string[]> = new Map()
   private ambiguousReferences: Set<string> = new Set()
+  private sourceProvenanceByBuildInfoPath: Map<string, BuildInfoSourceProvenance> = new Map()
 
   /**
    * Main entry point that orchestrates the discovery and hydration process
    */
   public async loadFrom(projectRoot: string): Promise<void> {
-    // Step 1: Discover all .json files
-    const files = await this.findContractFiles(projectRoot)
+    const files = await this.findProjectFiles(projectRoot)
 
-    // Step 2: Parse and hydrate contracts from all discovered files
-    for (const filePath of files) {
+    await this.loadSourceProvenanceFiles(files.sourceFiles)
+
+    for (const filePath of files.contractFiles) {
       try {
         const content = await fs.readFile(filePath, 'utf-8')
         await this.parseAndHydrateFromFile(content, filePath)
@@ -27,7 +30,6 @@ export class ContractRepository {
       }
     }
 
-    // Step 3: Build reference maps and identify ambiguous references
     this.disambiguateReferences()
   }
 
@@ -40,6 +42,7 @@ export class ContractRepository {
       const extractedContracts = parseBuildInfo(content, filePath)
       if (extractedContracts) {
         for (const extracted of extractedContracts) {
+          const sourceProvenance = this.getSourceProvenance(filePath, extracted.fullyQualifiedName)
           this.hydrateContract({
             creationCode: extracted.bytecode,
             runtimeBytecode: extracted.deployedBytecode,
@@ -49,6 +52,7 @@ export class ContractRepository {
             source: extracted.source,
             compiler: extracted.compiler,
             buildInfoId: extracted.buildInfoId,
+            sourceProvenance,
           }, filePath)
         }
         return
@@ -82,6 +86,7 @@ export class ContractRepository {
     source?: string
     compiler?: any
     buildInfoId?: string
+    sourceProvenance?: SourceProvenance
   }, sourceFilePath: string): void {
     // Validate that we have creation code for hashing (but allow empty string)
     if (data.creationCode === null || data.creationCode === undefined) {
@@ -97,7 +102,8 @@ export class ContractRepository {
       contract = {
         uniqueHash,
         creationCode: data.creationCode,
-        _sources: new Set<string>()
+        _sources: new Set<string>(),
+        _sourceProvenance: new Map<string, SourceProvenance>()
       }
       this.contracts.set(uniqueHash, contract)
     }
@@ -130,6 +136,28 @@ export class ContractRepository {
     if (data.buildInfoId && !contract.buildInfoId) {
       contract.buildInfoId = data.buildInfoId
     }
+    if (data.sourceProvenance) {
+      if (!contract._sourceProvenance) {
+        contract._sourceProvenance = new Map<string, SourceProvenance>()
+      }
+      contract._sourceProvenance.set(sourceFilePath, data.sourceProvenance)
+
+      contract.sourceProvenance = this.selectPreferredSourceProvenance(contract._sourceProvenance)
+    }
+  }
+
+  private getSourceProvenance(buildInfoPath: string, fullyQualifiedName: string): SourceProvenance | undefined {
+    const provenance = this.sourceProvenanceByBuildInfoPath.get(buildInfoPath)
+    if (!provenance) {
+      return undefined
+    }
+
+    return mergeSourceProvenance(provenance, provenance.contracts?.[fullyQualifiedName])
+  }
+
+  private selectPreferredSourceProvenance(sourceProvenance: Map<string, SourceProvenance>): SourceProvenance | undefined {
+    const firstEntry = Array.from(sourceProvenance.entries()).sort(([a], [b]) => a.localeCompare(b))[0]
+    return firstEntry?.[1]
   }
 
   /**
@@ -269,6 +297,7 @@ export class ContractRepository {
     source?: string
     compiler?: any
     buildInfoId?: string
+    sourceProvenance?: SourceProvenance
     _path: string
     _hash: string
   }): void {
@@ -281,17 +310,21 @@ export class ContractRepository {
       source: contractData.source,
       compiler: contractData.compiler,
       buildInfoId: contractData.buildInfoId,
+      sourceProvenance: contractData.sourceProvenance,
     }, contractData._path)
 
     // For testing, immediately disambiguate references after adding
     this.disambiguateReferences()
   }
 
-  /**
-   * Recursively finds all files that might contain contracts (e.g., .json files)
-   */
-  private async findContractFiles(dir: string, ignoreDirs: Set<string> = new Set(['node_modules', 'dist', '.git', '.idea', '.vscode'])): Promise<string[]> {
-    let results: string[] = []
+  private async findProjectFiles(
+    dir: string,
+    ignoreDirs: Set<string> = new Set(['node_modules', 'dist', '.git', '.idea', '.vscode'])
+  ): Promise<{ contractFiles: string[]; sourceFiles: string[] }> {
+    const results: { contractFiles: string[]; sourceFiles: string[] } = {
+      contractFiles: [],
+      sourceFiles: []
+    }
     try {
       const list = await fs.readdir(dir, { withFileTypes: true })
 
@@ -299,10 +332,14 @@ export class ContractRepository {
         const fullPath = path.resolve(dir, dirent.name)
         if (dirent.isDirectory()) {
           if (!ignoreDirs.has(dirent.name)) {
-            results = results.concat(await this.findContractFiles(fullPath, ignoreDirs))
+            const childResults = await this.findProjectFiles(fullPath, ignoreDirs)
+            results.contractFiles.push(...childResults.contractFiles)
+            results.sourceFiles.push(...childResults.sourceFiles)
           }
         } else if (dirent.isFile() && dirent.name.endsWith('.json')) {
-          results.push(fullPath)
+          results.contractFiles.push(fullPath)
+        } else if (dirent.isFile() && (dirent.name === 'source.yaml' || dirent.name === 'source.yml')) {
+          results.sourceFiles.push(fullPath)
         }
       }
     } catch (err) {
@@ -310,4 +347,65 @@ export class ContractRepository {
     }
     return results
   }
-}
+
+  private async loadSourceProvenanceFiles(sourceFiles: string[]): Promise<void> {
+    this.sourceProvenanceByBuildInfoPath.clear()
+
+    for (const sourceFilePath of sourceFiles) {
+      let sourceDocument
+      try {
+        const content = await fs.readFile(sourceFilePath, 'utf-8')
+        sourceDocument = parseSourceDocument(content)
+      } catch (error) {
+        this.warnSourceProvenance(`Skipping source provenance file ${sourceFilePath}: ${error instanceof Error ? error.message : String(error)}`)
+        continue
+      }
+
+      if (!sourceDocument) {
+        continue
+      }
+
+      for (const warning of sourceDocument.warnings || []) {
+        this.warnSourceProvenance(`Skipping source provenance entry ${sourceFilePath}: ${warning}`)
+      }
+
+      const sourceDir = path.dirname(sourceFilePath)
+      for (const [buildInfoRef, provenance] of Object.entries(sourceDocument.build_info)) {
+        const buildInfoPath = path.resolve(sourceDir, buildInfoRef)
+        if (!isBuildInfoFile(buildInfoPath)) {
+          this.warnSourceProvenance(`Skipping source provenance entry ${sourceFilePath}: "${buildInfoRef}" does not point to a build-info JSON file.`)
+          continue
+        }
+
+        if (!await this.pathExists(buildInfoPath)) {
+          this.warnSourceProvenance(`Skipping source provenance entry ${sourceFilePath}: build-info file "${buildInfoRef}" does not exist.`)
+          continue
+        }
+
+        if (this.sourceProvenanceByBuildInfoPath.has(buildInfoPath)) {
+          this.warnSourceProvenance(`Skipping source provenance entry ${sourceFilePath}: duplicate provenance for build-info file "${buildInfoRef}".`)
+          continue
+        }
+
+        this.sourceProvenanceByBuildInfoPath.set(buildInfoPath, {
+          ...provenance,
+          sourceDocumentPath: sourceFilePath,
+          buildInfoPath
+        })
+      }
+    }
+  }
+
+  private async pathExists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  private warnSourceProvenance(message: string): void {
+    console.warn(message)
+  }
+}