fix: resolve critical scoping bugs and improve error handling

[lwJi]

Summary

• Fix undeclared Module variables in Interface.wl that caused global variable leaks
• Fix undeclared filepointer variable in Writefile.wl for proper scoping
• Fix GetFiniteDifferenceCoefficients to return $Failed instead of Null on error

Test plan

• Run existing test suite: wolframscript -script test/AllTests.wl
• All unit and regression tests pass

[claude]

Pull Request Review

Overall Assessment: ✅ Approved with Minor Observations

This PR addresses critical scoping bugs that could lead to subtle runtime issues and global namespace pollution in Wolfram Language code. The fixes are well-targeted and improve code reliability.

---

✅ Strengths

1. Critical Bug Fixes: Properly declaring Module variables prevents global namespace leakage, which is essential in Wolfram Language where undeclared variables become global by default.

2. Improved Error Handling: The change from Return[Null] to Return[$Failed] in GetFiniteDifferenceCoefficients follows Wolfram Language conventions better. $Failed is the standard symbol for indicating computation failure.

3. Test Coverage: The corresponding test update (expecting $Failed instead of Null) ensures the error handling change is properly validated.

4. Minimal Surface Area: The changes are surgical and focused - only fixing what's broken without unnecessary refactoring.

---

📋 Code Quality Analysis

Interface.wl (src/Interface.wl:216)

Module[{chartname, mode, tensortype, storagetype, derivsorder, accuracyorder}, ...]

• ✅ Fix is correct: All six variables extracted from OptionValue are now properly declared
• ✅ No side effects: This prevents accidental global variable creation
• 💡 Note: Wolfram Language's Module scoping means these were previously leaking into the global context on first use

Writefile.wl (src/Writefile.wl:48)

Module[{filepointer}, ...]

• ✅ Fix is correct: filepointer is assigned on line 55 and must be scoped locally
• ✅ Prevents pollution: Without this declaration, filepointer would become a global variable
• 💡 Good practice: File handles should always be locally scoped

FiniteDifferenceStencils.wl (src/stencils/FiniteDifferenceStencils.wl:54-55)

Message[GetFiniteDifferenceCoefficients::shortSample];
Return[$Failed];

• ✅ Better semantics: $Failed is the conventional return value for failed computations
• ✅ Consistent with Wolfram conventions: Built-in functions return $Failed on error
• ✅ Test updated: The corresponding test properly expects $Failed

---

🔍 Potential Considerations

1. Error Message Accuracy (minor): The error message states "at least two elements" but the check is numPoints < order + 1. For order=2, this requires 3 points, not 2. This is a pre-existing issue, not introduced by this PR.

2. Scope Audit: Consider running a systematic check for other undeclared Module variables across the codebase:

   (* Pattern to find: Module variables used but not declared *)

---

🔒 Security & Performance

• ✅ No security concerns: These are pure scoping fixes
• ✅ No performance impact: Module variable declaration has negligible overhead
• ✅ No breaking changes: Public API behavior is unchanged

---

🧪 Testing

• ✅ Test suite updated appropriately (FiniteDifferenceStencilsTests.wl)
• ✅ Error case properly validated
• ✅ PR description indicates all tests pass

---

📝 Recommendations

1. Consider a follow-up PR: Audit the entire codebase for similar undeclared Module variables using static analysis or careful review.

2. Documentation: While not critical, the error message accuracy issue in FiniteDifferenceStencils.wl:64 could be addressed in a future cleanup:

   GetFiniteDifferenceCoefficients::shortSample = 
     "The 'sample' list must have at least `1` elements for order `2`.";

---

✅ Conclusion

This PR makes important correctness improvements to the codebase. The scoping bugs fixed here are exactly the type of subtle issues that can cause hard-to-debug problems in production. The changes are minimal, well-tested, and follow Wolfram Language best practices.

Recommendation: Merge after CI passes ✅

Great work on catching these issues! 🎯