vict00r99/rune-stone/rune-diff

How to Use

When given a RUNE spec and its corresponding implementation file, compare them and report every discrepancy.

Input: a RUNE spec (.rune or Markdown) + an implementation file (.py, .ts, .go, etc.). Output: a diff report listing all mismatches.

Comparison Areas

1. SIGNATURE Match

Compare the spec's SIGNATURE against the actual function declaration.

Check:

• Function name matches exactly
• Parameter names match
• Parameter types match
• Parameter order matches
• Return type matches
• Default values match

Example mismatch:

**SIGNATURE MISMATCH**
-Spec:  `def validate_coupon(code: str, coupons: list[dict], date: str) -> tuple[bool, str]`
-Code:  `def validate_coupon(coupon_code: str, coupon_list: list, current_date: str) -> dict`
-Issues:
  -Parameter renamed: `code` -> `coupon_code`
  -Parameter renamed: `coupons` -> `coupon_list`
  -Parameter renamed: `date` -> `current_date`
  -Type changed: `coupons` lost `[dict]` annotation
  -Return type changed: `tuple[bool, str]` -> `dict`

2. BEHAVIOR Coverage

For each WHEN/THEN rule in the spec, verify the implementation handles it.

Process:

1. List every BEHAVIOR rule from the spec
2. Find the corresponding code branch (if/elif/else, match/case, guard clause)
3. Verify the action matches (return value, exception type, error message)

Check:

• Every BEHAVIOR rule has a corresponding code branch
• The condition logic matches the spec
• The action (return/raise) matches the spec
• Error messages are character-for-character identical
• The ORDER of checks matches the spec (top to bottom)

Example mismatch:

**BEHAVIOR DRIFT**
-Rule: `WHEN code is empty THEN return (False, "Coupon code cannot be empty")`
-Code: `if not code: raise ValueError("Code required")`
-Issues:
  -Action changed: spec says `return (False, ...)` but code `raises ValueError`
  -Message changed: `"Coupon code cannot be empty"` -> `"Code required"`

3. Error Message Accuracy

Extract all error messages from the implementation and compare against BEHAVIOR.

Check:

• Every error message in the code appears in the spec
• Every error message in the spec appears in the code
• Messages match exactly (no typos, no rephrasing)

4. CONSTRAINTS Enforcement

For each CONSTRAINT in the spec, check if the implementation validates it.

Check:

• Each constraint has a validation check in the code
• The validation rejects the right inputs
• Constraints not in BEHAVIOR (preconditions) are documented but not necessarily enforced

Example mismatch:

**MISSING CONSTRAINT CHECK**
-Spec CONSTRAINT: `"email: maximum 254 characters (RFC 5321)"`
-Code: No length check found
-Impact: Emails longer than 254 chars will be accepted

5. EDGE_CASES Handling

For each EDGE_CASE in the spec, verify the implementation handles it correctly.

Check:

• The implementation produces the expected result for each edge case
• No edge cases are silently ignored

6. Extra Behavior (not in spec)

Identify behavior in the code that is NOT described in the spec.

Look for:

• Extra validation checks not in CONSTRAINTS or BEHAVIOR
• Additional error conditions
• Default values or fallback behavior not in the spec
• Logging, caching, or side effects not mentioned

Example:

**UNDOCUMENTED BEHAVIOR**
-Code has: `if len(email) > 254: return (False, "Email too long")`
-Spec: No BEHAVIOR rule or CONSTRAINT mentions max length
-Action: Add to spec or remove from code

Output Format

## RUNE Diff Report: `<function_name>`
 
**Spec:** `validate_coupon.rune`
**Code:** `src/coupon.py`
 
### SIGNATURE
-[MATCH] Function name: `validate_coupon`
-[MATCH] Parameters: `code`, `coupons`, `date`
-[DRIFT] Return type: spec says `tuple[bool, str]`, code returns `tuple[bool, dict | str]`
 
### BEHAVIOR
| Rule | Status | Detail |
|------|--------|--------|
| WHEN code is empty... | MATCH | Line 12 |
| WHEN code not found... | MATCH | Line 18 |
| WHEN coupon expired... | DRIFT | Message differs: "Coupon has expired" vs "Expired coupon" |
| OTHERWISE... | MATCH | Line 28 |
 
### ERROR MESSAGES
-[DRIFT] Line 22: `"Expired coupon"` should be `"Coupon has expired"`
 
### CONSTRAINTS
-[MATCH] code: non-empty string
-[MISSING] code: case-insensitive — code uses exact match instead
 
### EDGE_CASES
-[MATCH] empty code: handled
-[DRIFT] expires today: spec says "still valid" but code treats it as expired
 
### UNDOCUMENTED
-Line 8: `if not isinstance(code, str): raise TypeError` — not in spec
 
### Summary
-**Status:** DRIFT DETECTED
-**Matches:** 7
-**Drifts:** 3 (return type, error message, expiration logic)
-**Missing:** 1 (case-insensitive matching)
-**Undocumented:** 1 (type check)
-**Recommendation:** Update spec to match code, OR fix code to match spec (see details above)

Severity Levels

• MATCH — Spec and code agree.
• DRIFT — Spec and code disagree. Must be resolved (update one or the other).
• MISSING — Spec describes behavior the code doesn't implement.
• UNDOCUMENTED — Code has behavior the spec doesn't describe.

Rules

• Report findings, do not modify either the spec or the code
• Be precise: include line numbers from the implementation
• For each DRIFT, state clearly what the spec says vs what the code does
• Do not assume which side is "correct" — the user decides whether to update the spec or the code
• If the code has multiple implementations of the same spec (e.g., Python + TypeScript), compare each separately