Align Flow lib defs for Node.js path with v24 (#55006)

Summary:
Pull Request resolved: #55006

This is an AI-assisted change to align the Flow definitions for the `path` module with the Node.js docs as at v24.

**New APIs:**

1. **`matchesGlob(path, pattern)`** - Glob pattern matching (added in Node.js v22.5.0)
   - Returns `boolean` indicating if path matches the glob pattern
   - Supports standard glob syntax: `*`, `?`, `[...]`, `**`, etc.
   - Example: `path.matchesGlob('/foo/bar', '/foo/*')` returns `true`
   - https://nodejs.org/api/path.html#pathmatchesglobpath-pattern

2. **`toNamespacedPath(path)`** - Windows namespace-prefixed path conversion
   - On Windows: converts path to namespace-prefixed path (e.g., `\\?\C:\path`)
   - On POSIX: returns path unchanged
   - Enables access to paths longer than 260 characters on Windows
   - https://nodejs.org/api/path.html#pathtonamespacedpathpath

**Type Safety Improvements:**

3. **Replaced `any` types** - Proper typed interfaces
   - Changed `posix: any` → `posix: path$PlatformPath`
   - Changed `win32: any` → `win32: path$PlatformPath`
   - Added `path$PlatformPath` type definition with all methods and properties

4. **Modern Readonly syntax for inputs** - Following readonly rules
   - `format()` input: Changed to `Readonly<{root?, dir?, base?, ext?, name?}>`
   - Allows passing readonly types safely (inputs should be readonly)

5. **Made `parse()` return type exact** - Removed spread operator
   - Return type is now exact: `{root: string, dir: string, base: string, ext: string, name: string}`
   - Previously had `...` spread operator allowing extra properties
   - Note: Return type is NOT readonly (outputs are mutable so consumers can modify)

6. **PlatformPath includes parse return as readonly** - Consistency
   - Within `path$PlatformPath` type, the parse method returns `Readonly<{...}>`
   - This is for the type definition itself, not the actual module export

**References:**
- Node.js path module docs: https://nodejs.org/api/path.html
- Modern Flow syntax: exact-by-default, `Readonly<T>` for input parameters

Changelog: [Internal]
 ---
> Generated by [Confucius Code Assist (CCA)](https://www.internalfb.com/wiki/Confucius/Analect/Shared_Analects/Confucius_Code_Assist_(CCA)/)
[Confucius Session](https://www.internalfb.com/confucius?host=devvm45708.cln0.facebook.com&port=8086&tab=Chat&session_id=1a3aa26e-e5a9-11f0-8d47-71a4a90f0494&entry_name=Code+Assist), [Trace](https://www.internalfb.com/confucius?session_id=1a3aa26e-e5a9-11f0-8d47-71a4a90f0494&tab=Trace)

Reviewed By: vzaidman

Differential Revision: D89932753

fbshipit-source-id: 9ae777b0be2fdfee8ef4a71e9d1f9fd1cd395215

Author: robhogan

flow-typed/environment/node.js

@@ -814,7 +814,7 @@ declare module 'crypto' {
     callback: (err: ?Error, buffer: Buffer) => void,
   ): void;
   declare function randomUUID(
-    options?: $ReadOnly<{|disableEntropyCache?: boolean|}>,
+    options?: Readonly<{disableEntropyCache?: boolean}>,
   ): string;
   declare function timingSafeEqual(
     a: Buffer | $TypedArray | DataView,
@@ -1701,7 +1701,7 @@ declare module 'fs' {
     }>,
   ): void;
 
-  declare type GlobOptions<WithFileTypes: boolean> = $ReadOnly<{
+  declare type GlobOptions<WithFileTypes: boolean> = Readonly<{
     /**
      * Current working directory.
      * @default process.cwd()
@@ -2593,10 +2593,45 @@ declare module 'os' {
   declare var EOL: string;
 }
 
+type path$PlatformPath = {
+  normalize(path: string): string,
+  join(...parts: Array<string>): string,
+  resolve(...parts: Array<string>): string,
+  matchesGlob(path: string, pattern: string): boolean,
+  isAbsolute(path: string): boolean,
+  relative(from: string, to: string): string,
+  dirname(path: string): string,
+  basename(path: string, ext?: string): string,
+  extname(path: string): string,
+  sep: string,
+  delimiter: string,
+  parse(pathString: string): Readonly<{
+    root: string,
+    dir: string,
+    base: string,
+    ext: string,
+    name: string,
+  }>,
+  format(
+    pathObject: Readonly<{
+      root?: string,
+      dir?: string,
+      base?: string,
+      ext?: string,
+      name?: string,
+    }>,
+  ): string,
+  toNamespacedPath(path: string): string,
+  posix: path$PlatformPath,
+  win32: path$PlatformPath,
+  ...
+};
+
 declare module 'path' {
   declare function normalize(path: string): string;
   declare function join(...parts: Array<string>): string;
   declare function resolve(...parts: Array<string>): string;
+  declare function matchesGlob(path: string, pattern: string): boolean;
   declare function isAbsolute(path: string): boolean;
   declare function relative(from: string, to: string): string;
   declare function dirname(path: string): string;
@@ -2610,18 +2645,19 @@ declare module 'path' {
     base: string,
     ext: string,
     name: string,
-    ...
   };
-  declare function format(pathObject: {
-    root?: string,
-    dir?: string,
-    base?: string,
-    ext?: string,
-    name?: string,
-    ...
-  }): string;
-  declare var posix: any;
-  declare var win32: any;
+  declare function format(
+    pathObject: Readonly<{
+      root?: string,
+      dir?: string,
+      base?: string,
+      ext?: string,
+      name?: string,
+    }>,
+  ): string;
+  declare function toNamespacedPath(path: string): string;
+  declare var posix: path$PlatformPath;
+  declare var win32: path$PlatformPath;
 }
 
 declare module 'punycode' {
@@ -2867,7 +2903,7 @@ declare class stream$Duplex extends stream$Readable mixins stream$Writable {
   // $FlowFixMe[incompatible-exact] See above
   // $FlowFixMe[incompatible-type] See above
   static fromWeb(
-    pair: $ReadOnly<{
+    pair: Readonly<{
       readable: ReadableStream,
       writable: WritableStream,
     }>,
@@ -3379,30 +3415,30 @@ type util$InspectOptions = {
 };
 
 declare type util$ParseArgsOption =
-  | $ReadOnly<{|
+  | Readonly<{
       type: 'boolean',
       multiple?: false,
       short?: string,
       default?: boolean,
-    |}>
-  | $ReadOnly<{|
+    }>
+  | Readonly<{
       type: 'boolean',
       multiple: true,
       short?: string,
       default?: Array<boolean>,
-    |}>
-  | $ReadOnly<{|
+    }>
+  | Readonly<{
       type: 'string',
       multiple?: false,
       short?: string,
       default?: string,
-    |}>
-  | $ReadOnly<{|
+    }>
+  | Readonly<{
       type: 'string',
       multiple: true,
       short?: string,
       default?: Array<string>,
-    |}>;
+    }>;
 
 type util$ParseArgsOptionToValue<TOption> = TOption['type'] extends 'boolean'
   ? TOption['multiple'] extends true
@@ -3613,7 +3649,7 @@ declare module 'util' {
       | Modifiers
       | $ReadOnlyArray<ForegroundColors | BackgroundColors | Modifiers>,
     text: string,
-    options?: $ReadOnly<{
+    options?: Readonly<{
       stream?: ?stream$Stream,
       validateStream?: ?boolean,
     }>,