OSU-1514: introduce contract semver checks

.github/workflows/semver-check.yml

@@ -0,0 +1,44 @@
+name: Contract Semver Check
+
+on:
+  pull_request:
+    branches:
+      - main
+      - master
+      - develop
+    paths:
+      - 'src/**/*.sol'
+      - 'scripts/sol-semver.mjs'
+      - 'foundry.toml'
+      - 'remappings.txt'
+      - 'soldeer.lock'
+
+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: |
+          MERGE_BASE=$(git -c safe.directory="$PWD" merge-base "$BASE_REF" "$HEAD_REF")
+          node scripts/sol-semver.mjs check \
+            --old-ref "$MERGE_BASE" \
+            --new-ref "$HEAD_REF"

CONTRIBUTING.md

@@ -66,6 +66,27 @@ Main time cost of developing smart-contract is audits, not development itself. B
 ## 🛠️ Development Workflow
 - We use [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) as Git branching model.
 - We use a pre-commit hook to automatically format, lint and test, ensuring no surprises on continuous integration run.
+
+### Contract Semver Checks
+- Keep `API_VERSION` in sync with interface/storage changes for versioned contracts.
+- Semver classification is based on storage layout, ABI, and deployed bytecode diffs.
+- `scripts/sol-semver.mjs check` compares `old-ref` (PR target/base) vs `new-ref` (PR source/head).
+- Without `--contracts`, the checker:
+  - taking changed `.sol` files from `git diff --name-only <old-ref> <new-ref> -- src`
+  - failing if a changed contract has no declared `API_VERSION`
+  - resolving inspectable changed `path:ContractName` pairs with `forge inspect`
+  - analyzing all versioned contracts (those declaring `API_VERSION`) to catch transitive impacts
+- If discovery is ambiguous for a versioned file, pass `--contracts` explicitly.
+
+Run locally:
+```bash
+yarn semver:check --old-ref origin/develop --new-ref HEAD
+yarn semver:diff --old-ref origin/develop --new-ref HEAD --contract src/core/MultistrategyVault.sol:MultistrategyVault
+
+# Optional explicit scope override:
+node scripts/sol-semver.mjs check --old-ref origin/develop --new-ref HEAD --contracts src/core/MultistrategyVault.sol:MultistrategyVault
+```
+
 ## 🤝 Communication
 - Use clear, verbose language in all communications
 - Ask questions when something isn't clear

README.md

@@ -230,3 +230,6 @@ 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**:
+See `CONTRIBUTING.md` for semver policy and workflow details.

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",
     "storage:generate": "./script/storage.sh generate",
     "storage:check": "./script/storage.sh check",
     "init": "husky && shx chmod +x .husky/*",