From 086a1f1b01725ad60dfb34c85c52cffe76dfee1f Mon Sep 17 00:00:00 2001
From: Lily Skye <git@suchipi.tv>
Date: Fri, 20 Dec 2024 17:30:58 -0700
Subject: [PATCH] more help docs wip and etc

---
 src/api/commands/extname/extname.help.md      |  2 ++
 src/api/commands/ls/ls.help.md                |  4 ++-
 src/api/commands/pwd/pwd.ts                   |  7 -----
 src/api/commands/realpath/realpath.help.md    |  2 ++
 src/api/commands/sleep/sleep.help.md          |  4 +--
 src/api/commands/sleep/sleep.inc.d.ts         |  6 ++--
 src/api/commands/sleep/sleep_async.help.md    |  2 +-
 src/api/commands/sleep/sleep_sync.help.md     |  2 +-
 .../parse-script-args/parse-script-args.ts    |  1 -
 src/api/path/path.ts                          | 28 +++++++++++++++++++
 todo.txt                                      |  1 +
 11 files changed, 43 insertions(+), 16 deletions(-)

diff --git a/src/api/commands/extname/extname.help.md b/src/api/commands/extname/extname.help.md
index 2903e2e..b6cf52e 100644
--- a/src/api/commands/extname/extname.help.md
+++ b/src/api/commands/extname/extname.help.md
@@ -13,3 +13,5 @@ declare function extname(
   options?: { full?: boolean }
 ): string;
 ```
+
+See also `help(basename)`.
diff --git a/src/api/commands/ls/ls.help.md b/src/api/commands/ls/ls.help.md
index 94e962c..cd00c50 100644
--- a/src/api/commands/ls/ls.help.md
+++ b/src/api/commands/ls/ls.help.md
@@ -1,6 +1,8 @@
 # `ls` - Return directory contents
 
-Returns the contents of a directory, as absolute paths. `.` and `..` are omitted.
+Returns the contents of a directory, as an Array of absolute paths. `.` and `..` are omitted.
+
+If `ls()` is called with no directory, the present working directory (`pwd()`) is used.
 
 ```ts
 // Defined in yavascript/src/api/commands/ls
diff --git a/src/api/commands/pwd/pwd.ts b/src/api/commands/pwd/pwd.ts
index c5d0518..e454861 100644
--- a/src/api/commands/pwd/pwd.ts
+++ b/src/api/commands/pwd/pwd.ts
@@ -11,13 +11,6 @@ export function pwd(): Path {
 const initialPwd = pwd();
 Object.freeze(initialPwd);
 Object.freeze(initialPwd.segments);
-Object.defineProperty(initialPwd, "separator", {
-  configurable: false,
-  writable: false,
-  enumerable: true,
-
-  value: initialPwd.separator,
-});
 
 Object.defineProperty(pwd, "initial", {
   configurable: false,
diff --git a/src/api/commands/realpath/realpath.help.md b/src/api/commands/realpath/realpath.help.md
index a4bc447..bfe4dda 100644
--- a/src/api/commands/realpath/realpath.help.md
+++ b/src/api/commands/realpath/realpath.help.md
@@ -10,3 +10,5 @@ Provides the same functionality as the unix binary of the same name.
 // Defined in yavascript/src/api/commands/realpath
 declare function realpath(path: string | Path): Path;
 ```
+
+If you want to convert a relative path to an absolute path, but the path's target might NOT exist, use `Path.normalize`.
diff --git a/src/api/commands/sleep/sleep.help.md b/src/api/commands/sleep/sleep.help.md
index 3a5c63e..8506779 100644
--- a/src/api/commands/sleep/sleep.help.md
+++ b/src/api/commands/sleep/sleep.help.md
@@ -1,8 +1,8 @@
 # `sleep` - Wait the specified number of milliseconds
 
-`sleep` and `sleep.sync` block the current thread for at least the specified number of milliseconds, or maybe a tiny bit longer.
+`sleep` and `sleep.sync` block the current thread for at least the specified number of milliseconds, but maybe a tiny bit longer.
 
-`sleep.async` returns a Promise which resolves in at least the specified number of milliseconds, or maybe a tiny bit longer.
+`sleep.async` returns a Promise which resolves in at least the specified number of milliseconds, but maybe a tiny bit longer.
 
 `sleep` and `sleep.sync` block the current thread. `sleep.async` doesn't block the current thread.
 
diff --git a/src/api/commands/sleep/sleep.inc.d.ts b/src/api/commands/sleep/sleep.inc.d.ts
index 973b352..9d87968 100644
--- a/src/api/commands/sleep/sleep.inc.d.ts
+++ b/src/api/commands/sleep/sleep.inc.d.ts
@@ -1,13 +1,13 @@
 /**
  * Blocks the current thread for at least the specified number of milliseconds,
- * or maybe a tiny bit longer.
+ * but maybe a tiny bit longer.
  *
  * alias for `sleep.sync`.
  */
 declare var sleep: {
   /**
    * Blocks the current thread for at least the specified number of milliseconds,
-   * or maybe a tiny bit longer.
+   * but maybe a tiny bit longer.
    *
    * alias for `sleep.sync`.
    *
@@ -17,7 +17,7 @@ declare var sleep: {
 
   /**
    * Blocks the current thread for at least the specified number of milliseconds,
-   * or maybe a tiny bit longer.
+   * but maybe a tiny bit longer.
    *
    * @param milliseconds - The number of milliseconds to block for.
    */
diff --git a/src/api/commands/sleep/sleep_async.help.md b/src/api/commands/sleep/sleep_async.help.md
index a2b3038..2f98f15 100644
--- a/src/api/commands/sleep/sleep_async.help.md
+++ b/src/api/commands/sleep/sleep_async.help.md
@@ -1,6 +1,6 @@
 # `sleep.async` - Wait for a while without blocking the thread
 
-`sleep.async` returns a Promise which resolves in at least the specified number of milliseconds, or maybe a tiny bit longer.
+`sleep.async` returns a Promise which resolves in at least the specified number of milliseconds, but maybe a tiny bit longer.
 
 `sleep.async` doesn't block the current thread, so other JavaScript code (registered event handlers, async functions, timers, etc) can run while `sleep.async`'s return Promise is waiting to resolve. If this is not the behavior you want, use `sleep.sync` instead.
 
diff --git a/src/api/commands/sleep/sleep_sync.help.md b/src/api/commands/sleep/sleep_sync.help.md
index 6203b9e..bae3718 100644
--- a/src/api/commands/sleep/sleep_sync.help.md
+++ b/src/api/commands/sleep/sleep_sync.help.md
@@ -1,6 +1,6 @@
 # `sleep.sync` - Block the current thread for a while
 
-`sleep.sync` blocks the current thread for at least the specified number of milliseconds, or maybe a tiny bit longer.
+`sleep.sync` blocks the current thread for at least the specified number of milliseconds, but maybe a tiny bit longer.
 
 No other JavaScript code can run while `sleep.sync` is running. If this is not the behavior you want, use `sleep.async` instead.
 
diff --git a/src/api/parse-script-args/parse-script-args.ts b/src/api/parse-script-args/parse-script-args.ts
index f4e4402..5ad2d95 100644
--- a/src/api/parse-script-args/parse-script-args.ts
+++ b/src/api/parse-script-args/parse-script-args.ts
@@ -53,7 +53,6 @@ export function parseScriptArgs(
       }
 
       case Path: {
-        // TODO: Path hint should return Path object in flags object instead of string
         hintsForClef[key] = clefParse.Path;
         pathKeys.add(key);
         break;
diff --git a/src/api/path/path.ts b/src/api/path/path.ts
index f95665c..e8b443e 100644
--- a/src/api/path/path.ts
+++ b/src/api/path/path.ts
@@ -34,14 +34,18 @@ const windowsDefaultPathExt =
   ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC";
 
 class Path {
+  // [x] helpdocs done
   static OS_SEGMENT_SEPARATOR = os.platform === "win32" ? "\\" : "/";
+  // [x] helpdocs done
   static OS_ENV_VAR_SEPARATOR = os.platform === "win32" ? ";" : ":";
+  // [x] helpdocs done
   static OS_PROGRAM_EXTENSIONS = new Set(
     os.platform === "win32"
       ? (env.PATHEXT || windowsDefaultPathExt).split(";")
       : []
   );
 
+  // [x] helpdocs done
   static splitToSegments(inputParts: Array<string> | string): Array<string> {
     assert.type(
       inputParts,
@@ -60,6 +64,7 @@ class Path {
     );
   }
 
+  // [x] helpdocs done
   static detectSeparator<Fallback extends string | null = string>(
     input: Array<string> | string,
     // @ts-ignore might be instantiated with a different subtype
@@ -84,6 +89,7 @@ class Path {
     return fallback;
   }
 
+  // [ ] helpdocs done
   static normalize(
     ...inputs: Array<string | Path | Array<string | Path>>
   ): Path {
@@ -101,6 +107,7 @@ class Path {
     return new Path(...inputs).normalize();
   }
 
+  // [ ] helpdocs done
   static isAbsolute(path: string | Path): boolean {
     assert.type(path, types.or(types.string, types.Path));
 
@@ -111,9 +118,12 @@ class Path {
     }
   }
 
+  // [x] helpdocs done
   segments: Array<string>;
+  // [x] helpdocs done
   separator: string;
 
+  // [-] helpdocs done (sorta)
   constructor(...inputs: Array<string | Path | Array<string | Path>>) {
     assert.type(
       inputs,
@@ -135,6 +145,7 @@ class Path {
     this.separator = Path.detectSeparator(parts);
   }
 
+  // [x] helpdocs done
   static fromRaw(
     segments: Array<string>,
     separator: string = Path.OS_SEGMENT_SEPARATOR
@@ -148,6 +159,7 @@ class Path {
     return path;
   }
 
+  // [ ] helpdocs done
   normalize(): Path {
     // we clone this cause we're gonna mutate it
     const segments = [...this.segments];
@@ -185,6 +197,7 @@ class Path {
     return Path.fromRaw(newSegments, this.separator);
   }
 
+  // [ ] helpdocs done
   concat(...others: Array<string | Path | Array<string | Path>>): Path {
     assert.type(
       others,
@@ -201,6 +214,7 @@ class Path {
     return Path.fromRaw(this.segments.concat(otherSegments), this.separator);
   }
 
+  // [ ] helpdocs done
   isAbsolute(): boolean {
     const firstPart = this.segments[0];
 
@@ -214,6 +228,7 @@ class Path {
     return false;
   }
 
+  // [ ] helpdocs done
   clone(): this {
     // @ts-ignore could be instantiated with different subtype
     return (this.constructor as typeof Path).fromRaw(
@@ -222,6 +237,7 @@ class Path {
     );
   }
 
+  // [ ] helpdocs done
   relativeTo(
     dir: Path | string,
     options: { noLeadingDot?: boolean } = {}
@@ -250,6 +266,7 @@ class Path {
     }
   }
 
+  // [ ] helpdocs done
   toString(): string {
     let result = this.segments.join(this.separator);
     if (result == "") {
@@ -260,22 +277,27 @@ class Path {
     }
   }
 
+  // [ ] helpdocs done
   toJSON(): string {
     return this.toString();
   }
 
+  // [ ] helpdocs done
   basename(): string {
     return this.segments.at(-1) || "";
   }
 
+  // [ ] helpdocs done
   extname(options: { full?: boolean } = {}): string {
     return extname(this, options);
   }
 
+  // [ ] helpdocs done
   dirname(): Path {
     return this.replaceLast([]);
   }
 
+  // [ ] helpdocs done
   startsWith(value: string | Path | Array<string | Path>): boolean {
     value = new Path(value);
 
@@ -284,6 +306,7 @@ class Path {
     );
   }
 
+  // [ ] helpdocs done
   endsWith(value: string | Path | Array<string | Path>): boolean {
     value = new Path(value);
 
@@ -295,6 +318,7 @@ class Path {
     );
   }
 
+  // [ ] helpdocs done
   indexOf(
     value: string | Path | Array<string | Path>,
     fromIndex: number = 0
@@ -315,6 +339,7 @@ class Path {
     return -1;
   }
 
+  // [ ] helpdocs done
   includes(
     value: string | Path | Array<string | Path>,
     fromIndex: number = 0
@@ -322,6 +347,7 @@ class Path {
     return this.indexOf(value, fromIndex) !== -1;
   }
 
+  // [ ] helpdocs done
   replace(
     value: string | Path | Array<string | Path>,
     replacement: string | Path | Array<string | Path>
@@ -343,6 +369,7 @@ class Path {
     }
   }
 
+  // [ ] helpdocs done
   replaceAll(
     value: string | Path | Array<string | Path>,
     replacement: string | Path | Array<string | Path>
@@ -367,6 +394,7 @@ class Path {
     return currentPath;
   }
 
+  // [ ] helpdocs done
   replaceLast(replacement: string | Path | Array<string | Path>): Path {
     replacement = new Path(replacement);
 
diff --git a/todo.txt b/todo.txt
index f950728..0f47a02 100644
--- a/todo.txt
+++ b/todo.txt
@@ -29,3 +29,4 @@
 - [ ] repl sometimes needs you to press Ctrl+C more times than it should
 - [ ] fix chmod so it has add/remove semantics and respects existing perms
 - [ ] yavascript globals aren't set up in workers
+- [ ] add `.on("exit")` support to node-compat `process` shim