From 6f2cd9694e16041c0f7c8eabdbb0efe55dc4dd05 Mon Sep 17 00:00:00 2001
From: Mike Bland <mbland@acm.org>
Date: Sat, 30 Dec 2023 15:02:23 -0500
Subject: [PATCH] Emit file://url from main wrapper program

This seems more convenient than emitting a relative URL and forcing the
user to either run a command or open it another way.

This was made pretty easy thanks to Node's url.pathToFileURL().
---
 README.md         | 16 +++++++++-------
 index.js          |  3 ++-
 test/main.test.js |  6 +++---
 3 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index fc0eb10..fda7fc2 100644
--- a/README.md
+++ b/README.md
@@ -51,18 +51,20 @@ the path to your JSDoc config file):
 
 ### Opening the link
 
-Running the wrapper will generate the link to the generated `index.html` file, e.g.:
+Running the wrapper will generate the local `file://` URL to the generated
+`index.html` file, e.g.:
 
 ```text
-jsdoc/jsdoc-cli-wrapper/1.0.0/index.html
+file:///Users/.../jsdoc/jsdoc-cli-wrapper/1.0.0/index.html
 ```
 
-You can open this link from the command line via the following commands,
-replacing `path/to/index.html` with your actual `index.html` path:
+You can click on or copy this link to open it in your browser. You can also open
+this link from the command line via the following commands, replacing
+`path/to/index.html` with your actual `index.html` path:
 
-- **macOS**: `open path/to/index.html`
-- **Linux**: `xdg-open path/to/index.html`
-- **Windows**: `start path\to\index.html`
+- **macOS**: `open file:///path/to/index.html`
+- **Linux**: `xdg-open file:///path/to/index.html`
+- **Windows**: `start file:///C:/path/to/index.html`
 
 ## Motivation
 
diff --git a/index.js b/index.js
index 20668f7..a10462d 100755
--- a/index.js
+++ b/index.js
@@ -16,12 +16,13 @@
 
 import { runJsdoc } from './lib/index.js'
 import { exit, stdout } from 'node:process'
+import { pathToFileURL } from 'node:url'
 
 try {
   const {exitCode, indexHtml} = await runJsdoc(
     process.argv.slice(2), process.env, process.platform
   )
-  if (indexHtml !== undefined) stdout.write(`${indexHtml}\n`)
+  if (indexHtml !== undefined) stdout.write(`${pathToFileURL(indexHtml)}\n`)
   exit(exitCode)
 
 } catch (err) {
diff --git a/test/main.test.js b/test/main.test.js
index 6f9fd0f..f7e8447 100644
--- a/test/main.test.js
+++ b/test/main.test.js
@@ -11,7 +11,7 @@ import DestDirHelper from './DestDirHelper'
 import { afterEach, describe, expect, test } from 'vitest'
 import { spawn } from 'node:child_process'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const PATH_KEY = pathKey(process.platform)
 
@@ -69,10 +69,10 @@ describe('jsdoc-cli-wrapper', () => {
     const { destDir, indexPath } = await destDirHelper.createIndexHtml(
       'jsdoc-cli-wrapper-test-', 'old-subdir', 'Old and Busted'
     )
+    const result = pathToFileURL(indexPath.replace('old-subdir', 'new-subdir'))
 
     await expect(runMain('-d', destDir)).resolves.toStrictEqual({
-      exitCode: 0,
-      stdout: `${indexPath.replace('old-subdir', 'new-subdir')}\n`
+      exitCode: 0, stdout: `${result}\n`
     })
   })