override versions for specific samples

Author: aelmanaa

README.md

@@ -27,6 +27,26 @@ npm install && npm run dev
 - Navigation is JSON in `/src/config/sidebar.ts`
 - SEO metadata implementation: See [SEO Metadata Guide](SEO_METADATA_GUIDE.md) for technical writers
 
+### Version Overrides for Solidity Samples
+
+To use different package versions for specific sample files (e.g., for tutorials requiring specific versions), edit `version-overrides.json`:
+
+```json
+{
+  "overrides": [
+    {
+      "file": "samples/CCIP/example.sol",
+      "reason": "Tutorial requires specific version",
+      "versions": {
+        "@chainlink/contracts": "1.5.0"
+      }
+    }
+  ]
+}
+```
+
+See TypeScript types in `src/scripts/helper/pin-solver-dist.ts` for structure.
+
 ## Deploy Preview
 
 This repo is configured to automatically create a preview environment on Vercel when a PR is opened. After the deployment is approved, the Vercel bot will leave a comment with a link to the preview on your PR.

public/samples/CCIP/cct/TokenDependencies.sol

@@ -9,4 +9,4 @@ import {
   RegistryModuleOwnerCustom
 } from "@chainlink/contracts-ccip/contracts/tokenAdminRegistry/RegistryModuleOwnerCustom.sol";
 import {TokenAdminRegistry} from "@chainlink/contracts-ccip/contracts/tokenAdminRegistry/TokenAdminRegistry.sol";
-import {BurnMintERC20} from "@chainlink/contracts@1.4.0/src/v0.8/shared/token/ERC20/BurnMintERC20.sol";
+import {BurnMintERC20} from "@chainlink/contracts/src/v0.8/shared/token/ERC20/BurnMintERC20.sol";

src/scripts/helper/pin-solver-dist.ts

@@ -1,6 +1,27 @@
 import fs from "fs"
 import { glob } from "glob"
 import crypto from "crypto"
+import path from "path"
+
+/**
+ * Type definitions for version override configuration.
+ * Config file: version-overrides.json in project root
+ *
+ * Example:
+ * {
+ *   "description": "Optional description",
+ *   "overrides": [
+ *     {
+ *       "file": "samples/CCIP/example.sol",
+ *       "reason": "Why this override is needed",
+ *       "versions": {
+ *         "@chainlink/contracts": "1.5.0",
+ *         "@chainlink/contracts-ccip": "1.6.3"
+ *       }
+ *     }
+ *   ]
+ * }
+ */
 
 interface Dependencies {
   [key: string]: string
@@ -10,6 +31,18 @@ interface PinningStats {
   totalFiles: number
   packagesUpdated: { [key: string]: number }
   filesProcessed: string[]
+  overridesApplied: { [file: string]: string[] }
+}
+
+interface FileOverride {
+  file: string
+  reason?: string
+  versions: Dependencies
+}
+
+interface VersionOverridesConfig {
+  description?: string
+  overrides: FileOverride[]
 }
 
 /**
@@ -42,13 +75,75 @@ const getFileHash = (content: string): string => {
   return crypto.createHash("sha256").update(content).digest("hex")
 }
 
+/**
+ * Loads version override configuration from file.
+ * @returns The version overrides configuration, or null if file doesn't exist.
+ */
+const loadVersionOverrides = (): Map<string, Dependencies> => {
+  const overridesPath = path.join(process.cwd(), "version-overrides.json")
+
+  if (!fs.existsSync(overridesPath)) {
+    console.log("ℹ️  No version-overrides.json found. Using default versions for all files.")
+    return new Map()
+  }
+
+  try {
+    const config: VersionOverridesConfig = JSON.parse(fs.readFileSync(overridesPath, "utf8"))
+    const overridesMap = new Map<string, Dependencies>()
+
+    config.overrides.forEach((override) => {
+      // Normalize path separators for cross-platform compatibility
+      const normalizedPath = override.file.replace(/\\/g, "/")
+      overridesMap.set(normalizedPath, override.versions)
+
+      console.log(`📌 Loaded override for ${override.file}:`)
+      if (override.reason) {
+        console.log(`   Reason: ${override.reason}`)
+      }
+      Object.entries(override.versions).forEach(([pkg, version]) => {
+        console.log(`   - ${pkg}@${version}`)
+      })
+    })
+
+    return overridesMap
+  } catch (error) {
+    console.error("⚠️  Failed to load version-overrides.json:", error)
+    return new Map()
+  }
+}
+
+/**
+ * Determines which versions to use for a given file.
+ * @param filePath - The path to the file being processed.
+ * @param defaultVersions - The default versions from package.json.
+ * @param overridesMap - Map of file paths to their version overrides.
+ * @returns The versions to use for this file.
+ */
+const getVersionsForFile = (
+  filePath: string,
+  defaultVersions: Dependencies,
+  overridesMap: Map<string, Dependencies>
+): Dependencies => {
+  // Normalize the file path to match config format (relative to dist, remove dist prefix)
+  const normalizedPath = filePath.replace(/\\/g, "/").replace(/^.*?\/(samples\/.+\.sol)$/, "$1")
+
+  const override = overridesMap.get(normalizedPath)
+
+  if (override) {
+    // Merge override versions with defaults (override takes precedence)
+    return { ...defaultVersions, ...override }
+  }
+
+  return defaultVersions
+}
+
 /**
  * Pins the versions of dependencies in Solidity files based on the provided glob patterns.
  * @param globPatterns - Array of glob patterns used to find Solidity files.
- * @param versions - The object containing the dependencies and their corresponding versions.
+ * @param defaultVersions - The default object containing the dependencies and their corresponding versions.
  * @throws {Error} - If there are errors during the version pinning process.
  */
-const pinVersionsInSolidityFiles = async (globPatterns: string[], versions: Dependencies) => {
+const pinVersionsInSolidityFiles = async (globPatterns: string[], defaultVersions: Dependencies) => {
   try {
     const fileArrays = await Promise.all(globPatterns.map((pattern) => glob(pattern)))
     const allFiles = fileArrays.flat()
@@ -57,14 +152,24 @@ const pinVersionsInSolidityFiles = async (globPatterns: string[], versions: Depe
       totalFiles: allFiles.length,
       packagesUpdated: {},
       filesProcessed: [],
+      overridesApplied: {},
     }
 
+    // Load version overrides configuration
+    const overridesMap = loadVersionOverrides()
+
     allFiles.forEach((file) => {
       try {
         const originalContent = fs.readFileSync(file, "utf8")
         let content = originalContent
 
-        Object.entries(versions).forEach(([packageName, version]) => {
+        // Get the appropriate versions for this file (either default or overridden)
+        const versionsToUse = getVersionsForFile(file, defaultVersions, overridesMap)
+
+        // Track if this file uses overrides
+        const usesOverrides = overridesMap.has(file.replace(/\\/g, "/").replace(/^.*?\/(samples\/.+\.sol)$/, "$1"))
+
+        Object.entries(versionsToUse).forEach(([packageName, version]) => {
           const regex = new RegExp(`(import.*${packageName})(/)(?!@${version.replace(".", "\\.")})(.*?\\.sol)`, "g")
           const newContent = content.replace(regex, `$1@${version}/$3`)
 
@@ -73,6 +178,14 @@ const pinVersionsInSolidityFiles = async (globPatterns: string[], versions: Depe
               stats.packagesUpdated[packageName] = 0
             }
             stats.packagesUpdated[packageName]++
+
+            // Track which packages were overridden for this file
+            if (usesOverrides && versionsToUse[packageName] !== defaultVersions[packageName]) {
+              if (!stats.overridesApplied[file]) {
+                stats.overridesApplied[file] = []
+              }
+              stats.overridesApplied[file].push(`${packageName}@${version}`)
+            }
           }
           content = newContent
         })
@@ -102,6 +215,16 @@ const pinVersionsInSolidityFiles = async (globPatterns: string[], versions: Depe
     Object.entries(stats.packagesUpdated).forEach(([pkg, count]) => {
       console.log(`- ${pkg}: ${count} imports updated`)
     })
+
+    // Show files with overrides applied
+    if (Object.keys(stats.overridesApplied).length > 0) {
+      console.log("\n🎯 Files with custom version overrides:")
+      Object.entries(stats.overridesApplied).forEach(([file, packages]) => {
+        console.log(`- ${file}`)
+        packages.forEach((pkg) => console.log(`  └─ ${pkg}`))
+      })
+    }
+
     if (stats.filesProcessed.length > 0) {
       console.log("\nUpdated files:")
       stats.filesProcessed.forEach((file) => {

version-overrides.json

@@ -0,0 +1,13 @@
+{
+  "description": "Per-file package version overrides for Solidity samples. This allows specific files to use different versions than the global defaults defined in package.json.",
+  "overrides": [
+    {
+      "file": "samples/CCIP/cct/TokenDependencies.sol",
+      "reason": "Requires specific CCIP and contracts versions for CCT tutorial compatibility",
+      "versions": {
+        "@chainlink/contracts-ccip": "1.6.3",
+        "@chainlink/contracts": "1.5.0"
+      }
+    }
+  ]
+}