v0.4.2: auto-provided Office interop aliases for .csx scripts

Implements FR_office_script_interop_alias.md in full. Fixes the CS0104
ambiguous-reference papercut that hit every Windows Office script:
`Range`, `Exception`, `Application`, `Style`, `Font`, `Action`, `Page`
collide between the auto-imported interop namespace and the BCL. `Range`
was the worst because modern C# added `System.Range` for slicing, so
the common idiom `Range used = xlSheet.UsedRange;` failed until each
author re-typed `using Xl = global::Microsoft.Office.Interop.Excel;` at
the top of every .csx.

Mechanism (picked option b from the FR, not option a):

- New `IComBridgePlugin.ScriptUsingAliases` contract member (default
  empty, so non-Office plugins are zero-impact). Each Windows Office
  plugin overrides to return its conventional two-letter alias body:
  excel→Xl, word→Wd, powerpoint→Pp, outlook→Ol — all qualified to
  global::Microsoft.Office.Interop.*.
- ScriptHost.RunAsync concatenates contributed aliases onto a single
  preamble line at the top of the script source, preserves BOM +
  encoding so PDB emit still works (CS8055-free), then passes the
  combined stream to CSharpScript.Create.
- Diagnostic line/column spans in Roslyn compile errors are rewritten
  back to the author's real source via a regex over the diagnostic
  ToString(). Errors located inside the preamble itself are left
  untouched so plugin-author bugs surface loudly instead of presenting
  as "your script line 0."

Verified end-to-end:
- Positive: each of word/excel/powerpoint/outlook resolves Wd.Application,
  Xl.Application, Pp.Application, Ol.MailItem with NO author-declared
  alias.
- Negative: bare `Range` is still ambiguous CS0104 — we deliberately
  did NOT win the bare-name race against System.Range.
- Line-number remap: the CS0104 from the negative test reports the
  author's real line, not the +1 compiled line.

Mirrored to D:\Dev\ScripTree\lib\combridge\ and R:\ScripTree\lib\combridge\
per the CLAUDE.md deployment mandate; byte-sizes match the source
build (host 162304, Outlook.Mac DLL 30720 from v0.4.1).

Docs updated:
- LLM/scripting.md § Office namespace shadowing rewritten to lead with
  the auto-alias and show the fully-qualify fallback.
- LLM/troubleshooting.md gains a dedicated CS0104 entry with the alias
  table inline.
- FR_office_script_interop_alias.md stamped with implementation log
  noting the option taken and verification results.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 2 people

CHANGELOG.md

@@ -4,6 +4,84 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2] — auto-provided interop aliases for Office scripts
+
+Addresses `D:\Dev\FeatureRequests\ComBridge_FeatureRequests\FR_office_script_interop_alias.md`
+in full. Implements the FR's primary proposal (option **b** —
+plugin-contributed aliases rendered into a host preamble) rather than the
+doc-only fallback.
+
+### Why this exists
+
+Every Windows Office `.csx` hit the same CS0104 pain point: the interop
+namespace defines its own `Range`, `Exception`, `Application`, `Style`,
+`Font`, `Action`, `Page`, etc., colliding with the same-named BCL types.
+`Range` is the worst offender because modern C# added `System.Range` for
+slicing syntax — so the single most common Office idiom
+(`Range used = xlSheet.UsedRange;`) failed to compile until every
+script author re-typed `using Xl = global::Microsoft.Office.Interop.Excel;`
+at the top. The FR identified this pattern sitting latent in 15 scripts
+across the ScripTreeApps catalog, surfacing only on first run.
+
+### Added
+- **`IComBridgePlugin.ScriptUsingAliases`** — new optional contract
+  member. Returns alias bodies (e.g. `"Xl = global::Microsoft.Office.Interop.Excel"`);
+  the host renders them as `using <alias>;` directives. Default = empty,
+  so existing plugins (SolidWorks, all Mac plugins) compile and run
+  unchanged with zero behavior change.
+- **Alias preamble** in `ScriptHost.RunAsync` — concatenates each
+  plugin's contributed aliases onto a single first line of the script
+  source, preserving BOM + encoding so PDB emit still works
+  (CS8055-free) and non-ASCII characters in script bodies round-trip
+  intact. Roslyn `ScriptOptions.Imports` accepts namespaces but not
+  alias directives, so the preamble route is the only working option.
+- **Diagnostic line-number remapping** — `RemapDiagnosticLine` rewrites
+  the `(LINE,COL)` span in Roslyn diagnostic strings so compile errors
+  point at the author's real source. A CS0104 reported at compiled
+  line 168 surfaces as line 167 (matching what the author sees in their
+  editor). Errors inside the preamble itself (a plugin-author bug,
+  not a script-author bug) are left untouched so they're loud.
+- **Four Windows Office plugins now contribute their alias** —
+  `excel` → `Xl`, `word` → `Wd`, `powerpoint` → `Pp`, `outlook` → `Ol`
+  (all qualified to `global::Microsoft.Office.Interop.*`). Mac plugins
+  contribute nothing — they don't have an interop namespace to shadow.
+
+### What stays the same (deliberately)
+
+- **Bare `Range` is still ambiguous.** The alias only guarantees a
+  reliable qualifier (`Xl.Range`, `Wd.Range`) is always in scope; it
+  does NOT silently pick the Office type over `System.Range`. This is
+  the FR's explicit acceptance criterion — we don't want to win the
+  bare-name race for the author.
+- **`System.Exception` etc. still need to be qualified** (or you can
+  catch a non-colliding subtype like `COMException`). The new aliases
+  fix the Office-side qualifier, not the BCL side.
+- **Existing scripts that already declare `using Xl = …` keep working.**
+  Roslyn quietly accepts the duplicate (same alias to the same
+  namespace); we don't conflict with manual declarations.
+
+### Verified
+
+- Positive: a Word `.csx` containing `typeof(Wd.Application).FullName`
+  compiles and runs with NO author-declared alias.
+- Negative: a Word `.csx` containing bare `Range r;` still fails with
+  CS0104 between `Microsoft.Office.Interop.Word.Range` and
+  `System.Range` — confirming we didn't accidentally resolve the race.
+- Line-number remap: the CS0104 from the negative test surfaces at
+  `(2,1)` (the author's actual line in the .csx), not `(3,1)` —
+  proving the preamble offset is being subtracted.
+
+### Docs
+- `LLM/scripting.md` § "Office interop namespaces shadow common BCL
+  names" rewritten to lead with the auto-provided alias (recommended)
+  and show the fully-qualify fallback. New alias-mechanics note
+  explains the preamble + line remap for plugin authors.
+- `LLM/troubleshooting.md` gained a dedicated CS0104 entry covering
+  Office-interop / BCL collisions with the alias table inline and the
+  rationale for keeping bare `Range` ambiguous.
+- `FR_office_script_interop_alias.md` stamped with implementation log
+  noting which option was taken (b, not a) and why.
+
 ## [0.4.1] — outlook search on macOS
 
 Lifts the v0.4.0 deferral. The Mac Outlook plugin now ships a `search`

LLM/scripting.md

@@ -70,10 +70,56 @@ the DLL alongside the script and use `#r "path/to/MyLib.dll"`.
 ### ⚠ Office interop namespaces shadow common BCL names
 
 Every Office interop namespace defines its OWN `Exception`, `Application`,
-`Style`, `Action`, `Font`, `Page` etc. — these clash with `System.*`. Inside
-any Office script (Excel/Word/PowerPoint/Outlook on Windows), the plugin's
-`ScriptUsings` imports the interop namespace, so unqualified references
-become ambiguous.
+`Style`, `Action`, `Font`, `Page`, **and `Range`** — these clash with
+`System.*`. Inside any Office script (Excel/Word/PowerPoint/Outlook on
+Windows), the plugin's `ScriptUsings` imports the interop namespace, so
+unqualified references become ambiguous.
+
+`Range` is the worst offender because modern C# added `System.Range` (for
+`x[1..3]` slicing), so even the single most common Office idiom —
+`Range used = xlSheet.UsedRange;` — fails to compile with CS0104.
+
+### ✓ Two-letter alias (auto-provided, v0.4.2+) — the recommended pattern
+
+The four Windows Office plugins auto-contribute a conventional two-letter
+alias for their interop namespace, prepended to your script source before
+compile. You can write the qualified form **without declaring the alias
+yourself**:
+
+| Plugin | Auto-provided alias | Use as |
+|---|---|---|
+| `excel`      | `Xl = global::Microsoft.Office.Interop.Excel`      | `Xl.Range used = ws.UsedRange;` |
+| `word`       | `Wd = global::Microsoft.Office.Interop.Word`       | `Wd.Range rng = wdDoc.Content;` |
+| `powerpoint` | `Pp = global::Microsoft.Office.Interop.PowerPoint` | `Pp.Shape sh = slide.Shapes[1];` |
+| `outlook`    | `Ol = global::Microsoft.Office.Interop.Outlook`    | `Ol.MailItem msg = (Ol.MailItem)item;` |
+
+```csharp
+// ✓ works in v0.4.2+ — no `using Xl = ...;` needed
+Xl.Range used = xlSheet.UsedRange;
+foreach (Xl.Range row in used.Rows) { /* ... */ }
+catch (System.Exception ex) { Console.WriteLine(ex.Message); }
+```
+
+Note that **bare `Range` is still ambiguous** — this is deliberate. The
+alias only guarantees a reliable qualifier (`Xl.Range`) is always in scope;
+it does NOT try to silently pick the Office type over `System.Range`.
+
+#### Mechanics (only matters if you're debugging a weird error)
+
+The host prepends `using Xl = global::Microsoft.Office.Interop.Excel; ` to
+the script source as a one-line preamble before passing it to Roslyn.
+Compile-error line/column numbers are remapped back to the author's real
+source — a CS0104 reported at "line 168" of the compiled source surfaces as
+line 167 of your .csx, matching what you'd see in an editor.
+
+If you need to inspect the preamble or contribute one from your own
+plugin, see `IComBridgePlugin.ScriptUsingAliases` in
+`src/ComBridge.Core/IComBridgePlugin.cs`.
+
+### Fallback: fully-qualify the BCL type
+
+If you'd rather not use the alias (or you're on a combridge older than
+v0.4.2), fully-qualify the BCL side instead:
 
 ```csharp
 // ❌ fails in any Outlook .csx with:
@@ -87,15 +133,17 @@ try { ... }
 catch (System.Exception ex) { Console.WriteLine(ex.Message); }
 ```
 
-Common collisions to fully-qualify when writing Office scripts:
-
-| BCL type | Use as |
-|---|---|
-| `Exception` | `System.Exception` |
-| `Action` | `System.Action` (for delegates; Office's `Action` is different) |
-| `Style` | `System.Drawing.Style` if you actually want it; otherwise just don't import `System.Drawing` |
-| `Font`, `Color` | `System.Drawing.Font` / `System.Drawing.Color` |
-| `Page` (PPT) | `System.Web.Page` etc. |
+Common collisions to fully-qualify (or use the auto-provided alias on the
+Office side):
+
+| BCL type | Use as | Or |
+|---|---|---|
+| `Range` (modern C# slicing) | `System.Range` | `Xl.Range` / `Wd.Range` |
+| `Exception` | `System.Exception` | `Ol.Exception` (rarely what you want) |
+| `Action` | `System.Action` (delegate) | `Wd.Action` / `Pp.Action` (different concept) |
+| `Style`, `Font`, `Color` | `System.Drawing.*` | `Wd.Style` / `Xl.Style` / `Pp.Style` |
+| `Page` | `System.Web.Page` | `Wd.Page` / `Pp.Page` |
+| `Application` | `System.Windows.Application` | `Xl.Application` etc. |
 
 Or restructure to avoid the conflict: throw and let the host log it
 instead of `catch`ing, or catch a more specific type

LLM/troubleshooting.md

@@ -6,6 +6,58 @@ the right section based on when the error fires.
 
 ## Build-time errors
 
+### `error CS0104: 'Range' is an ambiguous reference between 'Microsoft.Office.Interop.Word.Range' and 'System.Range'` (or `Exception`, `Application`, `Style`, …)
+
+**Symptom.** A `.csx` running under any Windows Office plugin
+(`excel` / `word` / `powerpoint` / `outlook`) fails to compile with
+CS0104 on a bare identifier the BCL and the Office interop namespace
+both define. Most common offender is `Range` because modern C# added
+`System.Range` for slicing syntax.
+
+**Why.** The Office plugin's `ScriptUsings` imports the interop
+namespace so authors can write `Application`, `Range`, etc. unqualified.
+But that namespace also defines its own `Exception`, `Application`,
+`Style`, `Action`, `Font`, `Range`, etc. that collide with `System.*`.
+Roslyn refuses to pick one.
+
+**Fix (v0.4.2+ — recommended).** Use the **auto-provided two-letter
+alias** the plugin contributes to your script. No `using ... = ...`
+declaration needed — it's already in scope:
+
+```csharp
+Xl.Range used = xlSheet.UsedRange;     // not bare Range
+Wd.Range rng  = wdDoc.Content;
+catch (System.Exception ex) { ... }    // qualify the BCL side
+```
+
+Alias table:
+
+| Plugin       | Auto-alias                                           |
+|--------------|-----------------------------------------------------|
+| `excel`      | `Xl = global::Microsoft.Office.Interop.Excel`      |
+| `word`       | `Wd = global::Microsoft.Office.Interop.Word`       |
+| `powerpoint` | `Pp = global::Microsoft.Office.Interop.PowerPoint` |
+| `outlook`    | `Ol = global::Microsoft.Office.Interop.Outlook`    |
+
+**Fix (older combridge).** Either declare the alias yourself at the
+top of the .csx:
+
+```csharp
+using Xl = global::Microsoft.Office.Interop.Excel;
+Xl.Range used = xlSheet.UsedRange;
+```
+
+…or fully-qualify the BCL side every time (`System.Exception`,
+`System.Range`, etc.). See `LLM/scripting.md` § "Office interop
+namespaces shadow common BCL names" for the full collision table.
+
+**Note: bare `Range` stays ambiguous on purpose.** The auto-alias
+guarantees a reliable qualifier is in scope; it does NOT silently win
+the race against `System.Range`. If you want bare `Range` to mean the
+Office type, add `using Range = Xl.Range;` to your own script.
+
+See FR `FR_office_script_interop_alias.md` for the design rationale.
+
 ### `error COMBRIDGE001: ... could not locate its required interop assemblies`
 
 **Cause.** A plugin declared `@(RequiredInteropFile)` items in its csproj

src/ComBridge.Core/IComBridgePlugin.cs

@@ -48,6 +48,38 @@ public interface IComBridgePlugin
     /// <summary>Namespaces auto-imported in user scripts.</summary>
     IEnumerable<string> ScriptUsings { get; }
 
+    /// <summary>
+    /// C# alias directives the host prepends to the script source before
+    /// compiling, one per element. Each element is the alias body WITHOUT
+    /// the leading <c>using</c> keyword and WITHOUT the trailing semicolon,
+    /// e.g. <c>"Wd = global::Microsoft.Office.Interop.Word"</c> — the host
+    /// emits <c>using Wd = global::Microsoft.Office.Interop.Word;</c>.
+    /// <para>
+    /// Why this exists separately from <see cref="ScriptUsings"/>: Roslyn's
+    /// <c>ScriptOptions.Imports</c> accepts namespaces and <c>static</c>
+    /// usings but NOT alias directives, so an alias can't be contributed
+    /// the same way namespaces are. The script host works around it by
+    /// rendering aliases into a one-line preamble at the top of the script
+    /// source and remapping diagnostic line numbers back to the author's
+    /// real source. See <see cref="ScriptHost.RunAsync"/>.
+    /// </para>
+    /// <para>
+    /// Purpose: solve the CS0104 Office-interop / BCL name collision
+    /// (<c>Range</c>, <c>Exception</c>, <c>Application</c>, <c>Style</c>, …)
+    /// without making every author re-type the alias in every <c>.csx</c>.
+    /// Default = empty. Office plugins (Word/Excel/PowerPoint/Outlook on
+    /// Windows) override to contribute their conventional two-letter alias
+    /// (<c>Wd</c>/<c>Xl</c>/<c>Pp</c>/<c>Ol</c>).
+    /// </para>
+    /// <para>
+    /// We deliberately do NOT try to win the bare-name race — bare
+    /// <c>Range</c> stays ambiguous. The alias only guarantees a reliable
+    /// qualifier (<c>Wd.Range</c>, <c>Xl.Range</c>) is always in scope.
+    /// </para>
+    /// <para>See FR <c>FR_office_script_interop_alias.md</c>.</para>
+    /// </summary>
+    IEnumerable<string> ScriptUsingAliases => Array.Empty<string>();
+
     /// <summary>
     /// Plugin-specific commands (in addition to the built-in <c>run-script</c>).
     /// Examples: SW <c>checkpoint</c>, Excel <c>dump-sheet</c>.

src/ComBridge.Core/ScriptHost.cs

@@ -1,3 +1,5 @@
+using System.Text;
+using System.Text.RegularExpressions;
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp.Scripting;
 using Microsoft.CodeAnalysis.Scripting;
@@ -136,13 +138,41 @@ public static async Task<int> RunAsync(
             loader.RegisterDependency(plugin.GetType().Assembly);
             loader.RegisterDependency(plugin.GlobalsType.Assembly);
 
-            using var scriptStream = File.OpenRead(scriptPath);
-            var script = CSharpScript.Create(scriptStream, options, plugin.GlobalsType, loader);
+            // Build the alias preamble (FR_office_script_interop_alias.md).
+            // Each plugin-contributed alias is rendered as `using <alias>; `
+            // and the whole set is concatenated onto a SINGLE first line so
+            // line-number offsetting is exactly 1 (the script body's line 1
+            // becomes compiled line 2). If a plugin contributes nothing, the
+            // preamble is empty and there's zero behavior change.
+            var aliases = plugin.ScriptUsingAliases?.ToList() ?? new List<string>();
+            string preamble = aliases.Count == 0
+                ? ""
+                : string.Concat(aliases.Select(a => $"using {a}; ")) + "\n";
+            int preambleLineOffset = preamble.Length == 0 ? 0 : 1;
+
+            // To keep PDB emit happy (CS8055 needs explicit encoding), we
+            // build a MemoryStream that preserves the source file's BOM (if
+            // any) and uses the matching encoding for the preamble bytes.
+            // Without this, mixing UTF-8-BOM script content with default-
+            // encoded preamble would corrupt non-ASCII characters in the body.
+            byte[] scriptBytes = File.ReadAllBytes(scriptPath);
+            (Encoding enc, int bomLen) = DetectEncoding(scriptBytes);
+            using var ms = new MemoryStream(bomLen + preamble.Length * 2 + scriptBytes.Length);
+            if (bomLen > 0) ms.Write(scriptBytes, 0, bomLen);
+            if (preamble.Length > 0)
+            {
+                byte[] preBytes = enc.GetBytes(preamble);
+                ms.Write(preBytes, 0, preBytes.Length);
+            }
+            ms.Write(scriptBytes, bomLen, scriptBytes.Length - bomLen);
+            ms.Position = 0;
+
+            var script = CSharpScript.Create(ms, options, plugin.GlobalsType, loader);
             var diags = script.Compile();
             var errors = diags.Where(d => d.Severity == DiagnosticSeverity.Error).ToList();
             if (errors.Count > 0)
             {
-                foreach (var d in errors) output.WriteLine(d.ToString());
+                foreach (var d in errors) output.WriteLine(RemapDiagnosticLine(d.ToString(), preambleLineOffset));
                 return 3;
             }
             var state = await script.RunAsync(globals);
@@ -169,4 +199,50 @@ public static async Task<int> RunAsync(
             Console.SetError(originalErr);
         }
     }
+
+    /// <summary>
+    /// Detect the encoding + BOM length of raw source bytes. Default is
+    /// UTF-8 without BOM (Roslyn's expectation for the streaming overload).
+    /// </summary>
+    private static (Encoding enc, int bomLen) DetectEncoding(byte[] bytes)
+    {
+        if (bytes.Length >= 3 && bytes[0] == 0xEF && bytes[1] == 0xBB && bytes[2] == 0xBF)
+            return (new UTF8Encoding(true), 3);
+        if (bytes.Length >= 2 && bytes[0] == 0xFF && bytes[1] == 0xFE)
+            return (Encoding.Unicode, 2);     // UTF-16 LE
+        if (bytes.Length >= 2 && bytes[0] == 0xFE && bytes[1] == 0xFF)
+            return (Encoding.BigEndianUnicode, 2);  // UTF-16 BE
+        if (bytes.Length >= 4 && bytes[0] == 0 && bytes[1] == 0 && bytes[2] == 0xFE && bytes[3] == 0xFF)
+            return (Encoding.UTF32, 4);
+        return (new UTF8Encoding(false), 0);
+    }
+
+    /// <summary>
+    /// Rewrite Roslyn diagnostic strings so reported line numbers point at
+    /// the author's real source. Diagnostic text format is:
+    /// <c>&lt;path&gt;(LINE,COL): severity ID: message</c> — we capture
+    /// <c>(LINE,COL)</c> and subtract the preamble offset from LINE.
+    /// <para>
+    /// If the offending span is actually inside the injected preamble
+    /// (which would be a bug in the plugin's alias declaration, not the
+    /// author's script), we leave the line number alone so the bug is
+    /// visible rather than presenting as "your script line 0" gibberish.
+    /// </para>
+    /// </summary>
+    private static readonly Regex DiagLocRx = new(
+        @"\((?<line>\d+),(?<col>\d+)\)",
+        RegexOptions.Compiled);
+
+    private static string RemapDiagnosticLine(string diagText, int preambleLineOffset)
+    {
+        if (preambleLineOffset == 0) return diagText;
+        return DiagLocRx.Replace(diagText, m =>
+        {
+            int reportedLine = int.Parse(m.Groups["line"].Value);
+            int col = int.Parse(m.Groups["col"].Value);
+            int realLine = reportedLine - preambleLineOffset;
+            if (realLine < 1) return m.Value;  // preamble-side error — leave as-is
+            return $"({realLine},{col})";
+        });
+    }
 }

src/plugins/ComBridge.Plugins.Excel/ExcelPlugin.cs

@@ -103,6 +103,17 @@ public IEnumerable<MetadataReference> ScriptReferences
         "Microsoft.Office.Interop.Excel",
     };
 
+    /// <summary>
+    /// Auto-provide the conventional two-letter alias for the Excel interop
+    /// namespace so user .csx files can write <c>Xl.Range used = ws.UsedRange;</c>
+    /// without re-declaring <c>using Xl = global::Microsoft.Office.Interop.Excel;</c>
+    /// at the top of every script. See FR_office_script_interop_alias.md.
+    /// </summary>
+    public IEnumerable<string> ScriptUsingAliases => new[]
+    {
+        "Xl = global::Microsoft.Office.Interop.Excel",
+    };
+
     public IEnumerable<IBridgeCommand> Commands => new IBridgeCommand[]
     {
         new InfoCommand(),