feat: add predecessors package logic ported from create-proposal-pr composite action (#474)

We are moving the files related to opcounts and predecessor calculation
to this package to allow better reusability across all the GH workflows
as this is something that might be used in different mcms related
pipelines.

Main API's Exposed

#### Opcount computation related
**ComputeHighestOpCountsFromPredecessors**: Returns the newly computed
opcounts for the given PR and list of predecessors.
```go
func ComputeHighestOpCountsFromPredecessors(
	lggr logger.Logger,
	newProposalData ProposalsOpData,
	predecessors []PRView,
) map[mcmstypes.ChainSelector]uint64
```
**ApplyHighestOpCountsToProposal**: Applies the new opcounts provided to
the proposal and saves the proposal to the filesystem
```go
func ApplyHighestOpCountsToProposal(
	lggr logger.Logger,
	proposalPath string,
	newOpCounts map[mcmstypes.ChainSelector]uint64,
) 
```
**ParseProposalOpsData**: small helper to extract just the opcount
related information into an easier to access struct.
```go
func ParseProposalOpsData(ctx context.Context, filePath string) (ProposalsOpData, error)
```

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: ecPablo

.changeset/mighty-ways-kick.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+add predecessors and opcount calculation logic to proposalutils package.

experimental/proposalutils/helpers.go

@@ -0,0 +1,15 @@
+package proposalutils
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+)
+
+// MatchesProposalPath is a simple filter for proposal JSON files in the expected dir.
+func MatchesProposalPath(domain, environment, p string) bool {
+	p = filepath.ToSlash(p)
+	prefix := fmt.Sprintf("domains/%s/%s/proposals/", domain, environment)
+
+	return strings.HasPrefix(p, prefix) && strings.HasSuffix(p, ".json")
+}

experimental/proposalutils/predecessors/predecessor.go

@@ -0,0 +1,174 @@
+package predecessors
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/smartcontractkit/chainlink-common/pkg/logger"
+
+	"github.com/smartcontractkit/mcms"
+
+	mcmstypes "github.com/smartcontractkit/mcms/types"
+)
+
+// ComputeHighestOpCountsFromPredecessors looks at the given predecessors,
+// and for each chain present in 'newProposalData', computes the new starting
+// op count as: current StartingOpCount (from the new proposal) + SUM of the
+// number of ops across ALL predecessors that share the same chain selector
+// AND the same MCM address. We assume that the predecessors are sorted
+// from oldest to newest, so we can log them in that order.
+// Returns:
+//   - newStartPerChain: map[chain] = baseline + sum(ops)
+func ComputeHighestOpCountsFromPredecessors(
+	lggr logger.Logger,
+	newProposalData ProposalsOpData,
+	predecessors []PRView,
+) map[mcmstypes.ChainSelector]uint64 {
+	out := make(map[mcmstypes.ChainSelector]uint64, len(newProposalData))
+
+	lggr.Infof("Computing new starting op counts from %d predecessors...", len(predecessors))
+
+	for sel, cur := range newProposalData {
+		lggr.Infof("New proposal data - chain %d: MCM=%s start=%d ops=%d", uint64(sel), cur.MCMAddress, cur.StartingOpCount, cur.OpsCount)
+		baseline := cur.StartingOpCount
+		var extra uint64
+
+		for _, pred := range predecessors {
+			other, ok := pred.ProposalData[sel]
+			if !ok || !sameMCM(cur.MCMAddress, other.MCMAddress) {
+				continue
+			}
+
+			start := other.StartingOpCount
+			if start < baseline {
+				// Stale predecessor: its proposed start is below current on-chain baseline.
+				// Ignore to avoid double-counting or lowering.
+				lggr.Warnf("Skipping stale predecessor PR#%d on chain %d: pred.start=%d < baseline (ie onchain-value)=%d",
+					pred.Number, uint64(sel), start, baseline)
+
+				continue
+			}
+
+			extra += other.OpsCount
+			lggr.Infof("Counting predecessor PR#%d on chain %d: baseline=%d start=%d +ops=%d",
+				pred.Number, uint64(sel), baseline, start, other.OpsCount)
+		}
+
+		out[sel] = baseline + extra
+	}
+
+	// Handle case where a predecessor PR is merged between PR creation and execution:
+	// If the latest predecessor's op count is higher than the computed sum, adjust to match.
+	if len(predecessors) > 0 {
+		for sel, cur := range newProposalData {
+			// get most recent predecessor with same MCM address
+			latestPredecessor := predecessors[len(predecessors)-1]
+			other, ok := latestPredecessor.ProposalData[sel]
+			if !ok || !sameMCM(cur.MCMAddress, other.MCMAddress) {
+				continue
+			}
+			newStart := other.StartingOpCount + other.OpsCount
+			if newStart > out[sel] {
+				lggr.Warnf("sum of predecessors' ops on chain %d is %d, but latest predecessor PR#%d has ops=%d, adjusting new start from %d to %d. This can happen when a predecessor gets merged while this action is running, but is not executed on-chain", uint64(sel), out[sel]-cur.StartingOpCount, latestPredecessor.Number, other.OpsCount, out[sel], newStart)
+				out[sel] = newStart
+			}
+		}
+	}
+
+	lggr.Infof("Computed new starting op counts: %v", out)
+
+	return out
+}
+
+// ApplyHighestOpCountsToProposal updates the proposal file with the new starting op counts.
+func ApplyHighestOpCountsToProposal(
+	lggr logger.Logger,
+	proposalPath string,
+	newOpCounts map[mcmstypes.ChainSelector]uint64,
+) error {
+	// 1) load via mcms
+	prop, err := mcms.LoadProposal(mcmstypes.KindTimelockProposal, proposalPath)
+	if err != nil {
+		return fmt.Errorf("load proposal: %w", err)
+	}
+
+	// 2) cast to concrete type to mutate ChainMetadata
+	tp, ok := prop.(*mcms.TimelockProposal)
+	if !ok {
+		return fmt.Errorf("expected *mcms.TimelockProposal, got %T", prop)
+	}
+
+	// 3) bump starting op counts
+	changed := false
+	for sel, end := range newOpCounts {
+		meta, ok := tp.ChainMetadata[sel]
+		if !ok {
+			continue
+		}
+		newStart := end
+		if meta.StartingOpCount < newStart {
+			lggr.Infof("Updated startingOpCount: chain %d → %d", uint64(sel), end)
+			meta.StartingOpCount = newStart
+			tp.ChainMetadata[sel] = meta
+			changed = true
+		} else {
+			lggr.Warnf("Not updating startingOpCount for chain %d: current=%d, proposed=%d",
+				uint64(sel), meta.StartingOpCount, newStart)
+		}
+	}
+
+	if !changed {
+		lggr.Infof("No startingOpCount changes needed for %s", proposalPath)
+		return nil
+	}
+
+	// 4) write back using mcms helper
+	f, err := os.OpenFile(proposalPath, os.O_WRONLY|os.O_TRUNC|os.O_CREATE, 0o600)
+	if err != nil {
+		return fmt.Errorf("open for write: %w", err)
+	}
+	defer f.Close()
+
+	if err := mcms.WriteTimelockProposal(f, tp); err != nil {
+		return fmt.Errorf("write proposal: %w", err)
+	}
+
+	return nil
+}
+
+// ParseProposalOpsData uses mcms for a local file path (current proposal) to get op counts.
+func ParseProposalOpsData(ctx context.Context, filePath string) (ProposalsOpData, error) {
+	proposal, err := mcms.LoadProposal(mcmstypes.KindTimelockProposal, filePath)
+	if err != nil {
+		return nil, fmt.Errorf("load proposal from %s: %w", filePath, err)
+	}
+	// convert to timelock proposal
+	tp, ok := proposal.(*mcms.TimelockProposal)
+	if !ok {
+		return nil, fmt.Errorf("expected *mcms.TimelockProposal, got %T", proposal)
+	}
+
+	// Use conversion-aware counts
+	counts, err := tp.OperationCounts(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("converted operation counts: %w", err)
+	}
+
+	data := make(ProposalsOpData, len(proposal.ChainMetadatas()))
+	for chain, meta := range proposal.ChainMetadatas() {
+		data[chain] = McmOpData{
+			MCMAddress:      strings.TrimSpace(meta.MCMAddress),
+			StartingOpCount: meta.StartingOpCount,
+			OpsCount:        counts[chain],
+		}
+	}
+
+	return data, nil
+}
+
+// sameMCM is a tiny helper to check mcm addresses are equal
+func sameMCM(a, b string) bool {
+	return strings.EqualFold(strings.TrimSpace(a), strings.TrimSpace(b))
+}