feat: add semantic version checks for contracts

Author: 0xferit

.github/workflows/semver-check.yml

@@ -0,0 +1,42 @@
+name: Contract Semver Check
+
+on:
+  pull_request:
+    branches:
+      - main
+      - master
+      - develop
+    paths:
+      - 'src/**/*.sol'
+      - 'semver-lock.json'
+      - 'scripts/sol-semver.mjs'
+
+jobs:
+  check-semver:
+    name: Verify contract semantic version bumps
+    runs-on: general
+    container:
+      image: ${{ vars.GCP_DOCKER_IMAGE_REGISTRY }}/node-extended:f4f41461
+      credentials:
+        username: _json_key_base64
+        password: ${{ secrets.GCP_DOCKER_IMAGES_REGISTRY_SERVICE_ACCOUNT }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Init env
+        run: |
+          yarn install
+          forge soldeer install
+
+      - name: Check semantic version bumps in changed contracts
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.sha }}
+          HEAD_REF: ${{ github.event.pull_request.head.sha }}
+        run: |
+          node scripts/sol-semver.mjs check \
+            --old-ref "$BASE_REF" \
+            --new-ref "$HEAD_REF" \
+            --lock-file semver-lock.json

README.md

@@ -230,3 +230,16 @@ BaseStrategy (Abstract)
 3. Add strategy-specific tests in `test/unit/core/` or `test/unit/zodiac-core/`
 4. Create factory in `src/factories/` if permissionless deployment needed
 5. Update documentation with strategy-specific details
+
+**Contract semantic versioning checks**:
+1. Keep `API_VERSION` (or `VERSION`) in sync with contract interface/storage changes.
+2. Update `semver-lock.json` when a tracked contract version changes.
+3. Semver classification uses a single built-in mode based on storage, ABI, and bytecode layers.
+4. If a changed contract has no version constant, semver check fails and requires adding one in `X.Y.Z` format.
+5. Run local checks:
+
+```bash
+yarn semver:diff --old-ref origin/develop --new-ref HEAD --contract src/core/MultistrategyVault.sol:MultistrategyVault
+yarn semver:check --old-ref origin/develop --new-ref HEAD
+node scripts/sol-semver.mjs check --old-ref origin/develop --new-ref HEAD --lock-file semver-lock.json
+```

package.json

@@ -39,6 +39,8 @@
     "slither:setup": "python3 -m venv .venv && .venv/bin/pip3 install slither-analyzer",
     "slither": ".venv/bin/slither . --print human-summary",
     "slither:ci": "slither . --print human-summary --disable-color 2> reports/slither.txt; slither .",
+    "semver:diff": "node scripts/sol-semver.mjs diff",
+    "semver:check": "node scripts/sol-semver.mjs check --lock-file semver-lock.json",
     "storage:generate": "./script/storage.sh generate",
     "storage:check": "./script/storage.sh check",
     "init": "husky && shx chmod +x .husky/*",