Add parameter overrides to import magic

Support passing parameter overrides to #!import via a new --param flag. Adds a CLI-style parser (ParseArguments) and ResolveAndInjectParameters to coerce/validate overrides, merge them with imported notebook defaults, inject values into the variable store, and enforce required params (stopping execution with an error if missing). Updates command metadata/usage and error text, and expands tests to cover argument parsing, type coercion, validation, and integration scenarios where parameters are applied before executing code cells.

Author: TorreyBetts

src/Verso/MagicCommands/ImportMagicCommand.cs

@@ -1,11 +1,13 @@
 using Verso.Abstractions;
 using Verso.Extensions;
+using Verso.Parameters;
 
 namespace Verso.MagicCommands;
 
 /// <summary>
-/// <c>#!import path</c> — reads a notebook file, deserializes it, and executes all code cells
-/// in the current kernel session. Variables and state persist for subsequent cells.
+/// <c>#!import path [--param name=value ...]</c> — reads a notebook file, deserializes it, resolves
+/// parameters against the imported notebook's definitions, and executes all code cells in the current
+/// kernel session. Variables and state persist for subsequent cells.
 /// </summary>
 [VersoExtension]
 public sealed class ImportMagicCommand : IMagicCommand
@@ -20,11 +22,12 @@ public sealed class ImportMagicCommand : IMagicCommand
     // --- IMagicCommand ---
 
     public string Name => "import";
-    public string Description => "Imports and executes all code cells from another notebook file.";
+    public string Description => "Imports and executes all code cells from another notebook file, with optional parameter overrides.";
 
     public IReadOnlyList<ParameterDefinition> Parameters { get; } = new[]
     {
-        new ParameterDefinition("path", "Path to the notebook file to import.", typeof(string), IsRequired: true)
+        new ParameterDefinition("path", "Path to the notebook file to import.", typeof(string), IsRequired: true),
+        new ParameterDefinition("--param", "Parameter override in name=value format. May be repeated.", typeof(string), IsRequired: false)
     };
 
     public Task OnLoadedAsync(IExtensionHostContext context) => Task.CompletedTask;
@@ -37,12 +40,12 @@ public async Task ExecuteAsync(string arguments, IMagicCommandContext context)
         if (string.IsNullOrWhiteSpace(arguments))
         {
             await context.WriteOutputAsync(new CellOutput("text/plain",
-                "Error: #!import requires a file path. Usage: #!import <path>", IsError: true))
-                .ConfigureAwait(false);
+                "Error: #!import requires a file path. Usage: #!import <path> [--param name=value ...]",
+                IsError: true)).ConfigureAwait(false);
             return;
         }
 
-        var path = arguments.Trim();
+        var (path, paramOverrides) = ParseArguments(arguments);
 
         try
         {
@@ -90,6 +93,19 @@ await context.WriteOutputAsync(new CellOutput("text/plain",
                 }
             }
 
+            // Resolve parameters: explicit --param overrides first (with type
+            // coercion and validation), then fill remaining defaults from the
+            // imported notebook's definitions. Explicit overrides always win.
+            var paramError = ResolveAndInjectParameters(
+                notebook, paramOverrides, context.Variables);
+
+            if (paramError is not null)
+            {
+                await context.WriteOutputAsync(new CellOutput("text/plain",
+                    paramError, IsError: true)).ConfigureAwait(false);
+                return;
+            }
+
             var codeCellCount = 0;
             foreach (var cell in notebook.Cells)
             {
@@ -119,6 +135,102 @@ await context.WriteOutputAsync(new CellOutput("text/plain",
         }
     }
 
+    /// <summary>
+    /// Parses the arguments string into a file path and optional --param overrides.
+    /// </summary>
+    internal static (string Path, Dictionary<string, string> Params) ParseArguments(string arguments)
+    {
+        var parts = arguments.Split(' ', StringSplitOptions.RemoveEmptyEntries);
+        var path = parts[0];
+        var paramOverrides = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+
+        for (var i = 1; i < parts.Length; i++)
+        {
+            if (parts[i] is "--param" or "-p" && i + 1 < parts.Length)
+            {
+                var pair = parts[++i];
+                var eq = pair.IndexOf('=');
+                if (eq > 0)
+                    paramOverrides[pair[..eq]] = pair[(eq + 1)..];
+            }
+        }
+
+        return (path, paramOverrides);
+    }
+
+    /// <summary>
+    /// Resolves --param overrides and imported notebook defaults, validates required
+    /// parameters, and merges everything into the variable store. Returns an error
+    /// message if required parameters are missing, or null on success.
+    /// </summary>
+    internal static string? ResolveAndInjectParameters(
+        NotebookModel notebook,
+        Dictionary<string, string> paramOverrides,
+        IVariableStore variables)
+    {
+        var definitions = notebook.Parameters;
+
+        // If the imported notebook has no parameter definitions, inject any
+        // overrides as untyped strings and return.
+        if (definitions is not { Count: > 0 })
+        {
+            foreach (var (name, value) in paramOverrides)
+                variables.Set(name, value);
+            return null;
+        }
+
+        // 1. Apply explicit --param overrides with type coercion.
+        foreach (var (name, raw) in paramOverrides)
+        {
+            if (definitions.TryGetValue(name, out var def))
+            {
+                if (ParameterValueParser.TryParse(def.Type, raw, out var typed, out var error) && typed is not null)
+                    variables.Set(name, typed);
+                else
+                    return $"Error: Invalid value for parameter '{name}' ({def.Type}): {error}";
+            }
+            else
+            {
+                // Unknown parameter -- inject as string (matches CLI behavior).
+                variables.Set(name, raw);
+            }
+        }
+
+        // 2. Fill defaults for parameters not already in the store.
+        foreach (var (name, def) in definitions)
+        {
+            if (variables.TryGet<object>(name, out var existing) && existing is not null)
+                continue;
+
+            if (def.Default is null)
+                continue;
+
+            var value = def.Default;
+            if (value is string str && def.Type is not "string")
+            {
+                if (ParameterValueParser.TryParse(def.Type, str, out var parsed, out _) && parsed is not null)
+                    value = parsed;
+            }
+
+            variables.Set(name, value);
+        }
+
+        // 3. Validate required parameters.
+        var missing = new List<string>();
+        foreach (var (name, def) in definitions)
+        {
+            if (!def.Required) continue;
+            if (variables.TryGet<object>(name, out var val) && val is not null) continue;
+            missing.Add($"  {name} ({def.Type}){(def.Description is not null ? " -- " + def.Description : "")}");
+        }
+
+        if (missing.Count > 0)
+            return $"Error: Missing required parameter{(missing.Count > 1 ? "s" : "")} " +
+                   $"for imported notebook:\n{string.Join("\n", missing)}";
+
+        return null;
+    }
+
     /// <summary>
     /// Resolves a file path relative to the notebook's directory, or the current working directory
     /// if no notebook path is available.