fix: improve resolveSassCommand docs and restore sassPath option name

Add upstream references for sass.bat template and dart_cli_pkg#67.
Rename installDir back to sassPath for consistency with QUARTO_DART_SASS.

Author: cderv

src/core/dart-sass.ts

@@ -58,25 +58,36 @@ export async function dartCompile(
  */
 export interface DartCommandOptions {
   /**
-   * Override the dart-sass install directory.
+   * Override the path to the dart-sass install directory.
    * Used for testing with non-standard paths (spaces, accented characters).
    */
-  installDir?: string;
+  sassPath?: string;
 }
 
 /**
  * Resolve the dart-sass command and its base arguments.
  *
- * On Windows, calls dart.exe + sass.snapshot directly to avoid .bat file
- * issues: Deno quoting bugs (#13997), cmd.exe encoding (#14267), and
- * enterprise .bat blocking (#6651).
+ * On Windows, calls dart.exe + sass.snapshot directly instead of going
+ * through sass.bat. The bundled sass.bat is a thin wrapper generated by
+ * dart_cli_pkg that just runs:
+ *   "%SCRIPTPATH%\src\dart.exe" "%SCRIPTPATH%\src\sass.snapshot" %arguments%
+ *
+ * Template source:
+ *   https://github.com/google/dart_cli_pkg/blob/main/lib/src/templates/standalone/executable.bat.mustache
+ * Upstream issue to ship standalone .exe instead of .bat + dart.exe:
+ *   https://github.com/google/dart_cli_pkg/issues/67
+ *
+ * Bypassing sass.bat avoids multiple .bat file issues on Windows:
+ * - Deno quoting bugs with spaced paths (#13997)
+ * - cmd.exe OEM code page misreading UTF-8 accented paths (#14267)
+ * - Enterprise group policy blocking .bat execution (#6651)
  */
 function resolveSassCommand(options?: DartCommandOptions): {
   cmd: string;
   baseArgs: string[];
 } {
-  const installDir = options?.installDir;
-  if (installDir == null) {
+  const sassPath = options?.sassPath;
+  if (sassPath == null) {
     const dartOverrideCmd = Deno.env.get("QUARTO_DART_SASS");
     if (dartOverrideCmd) {
       if (!existsSync(dartOverrideCmd)) {
@@ -89,7 +100,7 @@ function resolveSassCommand(options?: DartCommandOptions): {
     }
   }
 
-  const sassDir = installDir ?? architectureToolsPath("dart-sass");
+  const sassDir = sassPath ?? architectureToolsPath("dart-sass");
 
   if (isWindows) {
     return {

tests/unit/dart-sass.test.ts

@@ -60,7 +60,7 @@ unitTest(
       Deno.writeTextFileSync(inputScss, "body { color: red; }");
 
       const result = await dartCommand([inputScss, outputCss], {
-        installDir: spacedSassDir,
+        sassPath: spacedSassDir,
       });
 
       assert(
@@ -106,7 +106,7 @@ unitTest(
       Deno.writeTextFileSync(inputScss, "body { color: blue; }");
 
       const result = await dartCommand([inputScss, outputCss], {
-        installDir: accentedSassDir,
+        sassPath: accentedSassDir,
       });
 
       assert(