fix(analyzing-weights): bind weight changes to the correct function via -W (#58)

## What & why

`analyzing-weights`'s `analyze-weight-diff.py` was mis-attributing
weight changes to the wrong functions and silently dropping flags.

The parser identifies each change's function from (1) the git `@@` hunk
header and (2) `fn NAME(...)` lines in the diff context. For Substrate
weight files **both fail**:

- Hunk headers show the enclosing `impl ... WeightInfo` block, never a
`fn`.
- The `fn NAME(...)` signature sits ~5 lines above the first changed
line (`// Minimum execution time` / `Weight::from_parts`), outside the
default 3-line context — so it usually isn't in the diff at all.

With neither available, `current_fn` stops advancing and changes from
several consecutive functions collapse into one bucket;
`parse_weight_block` then keeps only the last value per variable.

**Observed impact** on a full runtime weight regen (moonbeam #3767):
- A `per-y 3.9K → 18.8K (+386.9%)` change was reported against
`pay_one_collator_reward_best`, but it actually belongs to
`delegate_with_auto_compound` (verified in source: `3_861 → 18_800`).
- Reported **50** changed functions / 7 Section-3 flags; the real
numbers are **~1,040** functions / 22 flags.

## Fix

- **Require `git diff -W` (`--function-context`)** so the `fn` signature
is always present in the diff. Documented in both the script docstring
and `SKILL.md` (step 2), with an explanation of why it's needed.
- **Warn loudly** when a bucket merges multiple functions (detected via
>1 `Minimum execution time` line per bucket — the tell-tale of a diff
produced without `-W`) instead of emitting wrong numbers.

## Verification

- Without `-W`: prints the new warning (33 merged buckets on #3767).
- With `-W`: no warning, 1,037 functions, correct per-function
attribution (spot-checked against source).

Author: manuelmauro

moonbeam-engineering/skills/analyzing-weights/SKILL.md

@@ -25,17 +25,27 @@ Analyzes weight file changes between the current branch and a base branch to det
 
 ### 2) Generate and parse the weight diff
 
-Run the analysis script piping the git diff of weight files:
+Run the analysis script piping the git diff of weight files. **Always pass
+`-W` (`--function-context`)** — without it, attribution is wrong (see note
+below):
 
 ```bash
-git diff $(git merge-base <base-branch> HEAD)..HEAD -- '*/weights/*' \
+git diff -W $(git merge-base <base-branch> HEAD)..HEAD -- '*/weights/*' \
   | python3 scripts/analyze-weight-diff.py --threshold 50
 ```
 
 The script accepts:
 - `--file <path>` or stdin (piped diff)
 - `--threshold <N>` percentage threshold for flagging (default: 50)
 
+> **Why `-W` is required:** weight files put the `fn NAME(...)` signature ~5
+> lines above the first changed line, and git's hunk headers show the enclosing
+> `impl ... WeightInfo` block, not the `fn`. With the default 3-line context the
+> parser can't see where one function ends and the next begins, so it attributes
+> changes to the wrong function and drops some flags entirely. `-W` includes the
+> signature lines. The script prints a loud warning if it detects merged
+> functions (the tell-tale of a diff generated without `-W`).
+
 ### 3) Interpret the report
 
 The script produces 7 sections:

moonbeam-engineering/skills/analyzing-weights/scripts/analyze-weight-diff.py

@@ -2,15 +2,23 @@
 """
 Analyze git diff of Substrate weight files and flag significant changes.
 
+IMPORTANT: always generate the diff with `-W` (--function-context).
+Weight files place the `fn NAME(...)` signature ~5 lines above the first
+changed line, and git's hunk headers show the enclosing `impl ... WeightInfo`
+block rather than the `fn`. Without function context the parser cannot tell
+where one function ends and the next begins, so changes get attributed to the
+wrong function (and some are dropped). `-W` includes the signature lines so
+each weight block is bound to the correct function.
+
 Usage:
   # Compare current branch against a base branch:
-  git diff $(git merge-base <base-branch> HEAD)..HEAD -- '*/weights/*' | python3 scripts/analyze-weight-diff.py
+  git diff -W $(git merge-base <base-branch> HEAD)..HEAD -- '*/weights/*' | python3 scripts/analyze-weight-diff.py
 
-  # Or from a saved diff file:
+  # Or from a saved diff file (must have been produced with `git diff -W`):
   python3 scripts/analyze-weight-diff.py --file weight_diff.txt
 
   # Adjust the threshold for flagging changes (default: 50%):
-  python3 scripts/analyze-weight-diff.py --threshold 30
+  git diff -W ... | python3 scripts/analyze-weight-diff.py --threshold 30
 """
 
 import argparse
@@ -25,6 +33,10 @@ def parse_weight_block(lines):
         "base_ref": 0,
         "base_proof": 0,
         "min_execution_time": None,
+        # Number of "Minimum execution time" lines seen in this bucket. >1 means
+        # several functions were merged into one bucket (insufficient diff
+        # context) and attribution can no longer be trusted.
+        "min_exec_count": 0,
         "ref_multipliers": {},
         "proof_multipliers": {},
         "db_reads_base": 0,
@@ -39,6 +51,7 @@ def parse_weight_block(lines):
         )
         if min_match:
             result["min_execution_time"] = int(min_match.group(1).replace("_", ""))
+            result["min_exec_count"] += 1
             continue
 
         # Base Weight::from_parts — first occurrence NOT inside a saturating_add
@@ -239,6 +252,33 @@ def main():
     print(f"WEIGHT DIFF ANALYSIS (threshold: {threshold:.0f}%)")
     print(sep)
 
+    # Guard against insufficient diff context: if any bucket captured more than
+    # one "Minimum execution time" line, several functions were merged together
+    # and the diff was almost certainly generated without `-W`. Attribution is
+    # unreliable in that case, so warn loudly rather than print wrong numbers.
+    merged = [
+        c
+        for c in all_changes
+        if c["old"]["min_exec_count"] > 1 or c["new"]["min_exec_count"] > 1
+    ]
+    if merged:
+        print()
+        print("!" * 120)
+        print(
+            "WARNING: multiple functions were merged into a single block "
+            f"({len(merged)} affected). The diff was likely produced WITHOUT "
+            "function context."
+        )
+        print(
+            "         Per-function attribution below is UNRELIABLE. Regenerate "
+            "the diff with `-W`:"
+        )
+        print(
+            "           git diff -W $(git merge-base <base> HEAD)..HEAD -- "
+            "'*/weights/*' | python3 analyze-weight-diff.py"
+        )
+        print("!" * 120)
+
     # ------------------------------------------------------------------
     # OVERALL STATS
     # ------------------------------------------------------------------