feat: add stability scripting capabilities

docs/source/api/python/index.rst

@@ -8,3 +8,5 @@ Python API
    hydrostatics
    stability
    tanks
+   scripting
+   plotting

docs/source/api/python/plotting.rst

@@ -0,0 +1,22 @@
+Plotting
+========
+
+Utilities for visualizing criteria results.
+
+.. py:module:: navaltoolbox.plotting
+
+.. py:function:: plot_criteria_result(result, show=True, plot_id=None, save_to=None)
+
+   Plot the graphs defined in a CriteriaResult using Matplotlib.
+
+   :param result: The CriteriaResult object from a script execution.
+   :type result: CriteriaResult
+   :param show: If True, calls plt.show() after creating figures.
+   :type show: bool
+   :param plot_id: If provided, only plots the graph with this specific ID.
+   :type plot_id: str, optional
+   :param save_to: Path to save the plot. If multiple plots are generated, the plot ID will be appended to the filename.
+   :type save_to: str, optional
+   :returns: List of created matplotlib Figure objects.
+   :rtype: list[matplotlib.figure.Figure]
+   :raises ImportError: If matplotlib is not installed.

docs/source/api/python/scripting.rst

@@ -0,0 +1,154 @@
+Scripting
+=========
+
+Classes for Rhai scripting integration and criteria verification.
+
+Script Engine
+-------------
+
+.. py:class:: ScriptEngine
+
+   Rhai script execution engine.
+   
+   .. py:method:: run_script_file(path, context)
+   
+      Run a Rhai script from file.
+      
+      :param path: Path to .rhai script file
+      :type path: str
+      :param context: Data context for the script
+      :type context: CriteriaContext
+      :returns: Verification result
+      :rtype: CriteriaResult
+      :raises ValueError: If script execution fails
+      
+   .. py:method:: run_script(script, context)
+   
+      Run a Rhai script from string.
+      
+      :param script: Rhai script content
+      :type script: str
+      :param context: Data context for the script
+      :type context: CriteriaContext
+      :returns: Verification result
+      :rtype: CriteriaResult
+      
+Criteria Context
+----------------
+
+.. py:class:: CriteriaContext
+
+   Context for Rhai scripts, wrapping stability results.
+   
+   .. py:staticmethod:: from_result(result, vessel_name, loading_condition)
+   
+      Create a context from a CompleteStabilityResult.
+      
+      :param result: The stability calculation result
+      :type result: CompleteStabilityResult
+      :param vessel_name: Name of the vessel
+      :type vessel_name: str
+      :param loading_condition: Description of loading condition
+      :type loading_condition: str
+      :rtype: CriteriaContext
+      
+   .. py:method:: set_param(key, value)
+   
+      Set a parameter accessible to the script.
+      
+      :param key: Parameter name
+      :type key: str
+      :param value: Parameter value (str, float, or bool)
+      :type value: Union[str, float, bool]
+
+   .. py:method:: get_first_flooding_angle()
+   
+      Get the first angle where downflooding occurs.
+      
+      :returns: Angle in degrees or None
+      :rtype: Optional[float]
+
+   .. py:method:: find_equilibrium_angle(heeling_arm)
+   
+      Find the first stable equilibrium angle (where GZ = heeling_arm).
+      
+      :param heeling_arm: Heeling arm lever in meters
+      :type heeling_arm: float
+      :returns: Angle in degrees or None
+      :rtype: Optional[float]
+
+   .. py:method:: find_second_intercept(heeling_arm)
+   
+      Find the second intercept angle (unstable equilibrium).
+      
+      :param heeling_arm: Heeling arm lever in meters
+      :type heeling_arm: float
+      :returns: Angle in degrees or None
+      :rtype: Optional[float]
+
+Criteria Result
+---------------
+
+.. py:class:: CriteriaResult
+
+   Result of a criteria verification script.
+   
+   .. py:attribute:: overall_pass
+      :type: bool
+      
+      Whether all criteria passed.
+      
+   .. py:attribute:: pass_count
+      :type: int
+      
+      Number of passing criteria.
+      
+   .. py:attribute:: fail_count
+      :type: int
+      
+      Number of failing criteria.
+      
+   .. py:attribute:: criteria
+      :type: list[CriterionResult]
+      
+      List of individual criterion results.
+      
+   .. py:attribute:: plots
+      :type: list[str]
+      
+      List of plots data as JSON strings.
+
+Criterion Result
+----------------
+
+.. py:class:: CriterionResult
+
+   Result of a single criterion check.
+   
+   .. py:attribute:: name
+      :type: str
+      
+   .. py:attribute:: status
+      :type: str
+      
+      'PASS', 'FAIL', 'WARN', or 'N/A'.
+      
+   .. py:attribute:: actual_value
+      :type: float
+      
+   .. py:attribute:: required_value
+      :type: float
+      
+   .. py:attribute:: unit
+      :type: str
+      
+   .. py:attribute:: margin
+      :type: float
+      
+   .. py:attribute:: notes
+      :type: str
+      
+   .. py:attribute:: plot_id
+      :type: str
+      
+      ID of the associated plot, if any.