test(path): add additional tests to join (#5032)

add additional tests to stencil's wrapped version of `path.join`,
adding additional documentation to how the wrapped function works.
specifically, add tests to verify the following behavior:
1. how trailing slashes are treated by the function
2. how 1+ string arguments of '/' are handled
3. how relative paths going 'up' one directory level are handled such
   that only a file is resolved

the first case of trailing slashes is documented in JSDoc as well to
signify a divergence from `path.joing`. this behavior was the
impetus for this change - I didn't understand what I was seeing at first
when debugging some Stencil 4.x related path related bugs. this commit
is spun out from that work.

related to: #5029

src/utils/path.ts

@@ -219,12 +219,22 @@ export function relative(from: string, to: string): string {
  * normalization logic. This joins all the arguments (path fragments) into a
  * single path.
  *
+ * The calculation of the returned path follows that of Node's logic, with one exception - any trailing slashes will
+ * be removed from the calculated path.
+ *
  * @throws the underlying node function will throw if any argument is not a
  * string
  * @param paths the paths to join together
  * @returns a joined path!
  */
 export function join(...paths: string[]): string {
+  /**
+   * When normalizing, we should _not_ attempt to relativize the path returned by the native Node `join` method. When
+   * calculating the path from each of the string-based parts, Node does not prepend './' to any calculated path.
+   *
+   * Note that our algorithm does differ from Node's, as described in this function's JSDoc regarding trailing
+   * slashes.
+   */
   return normalizePath(path.join(...paths), false);
 }
 

src/utils/test/path.spec.ts

@@ -137,8 +137,13 @@ describe('normalizeFsPathQuery', () => {
   describe('wrapped nodejs path functions', () => {
     it('join should always return a POSIX path', () => {
       expect(join('foo')).toBe('foo');
+      expect(join('foo/')).toBe('foo');
       expect(join('foo', 'bar')).toBe('foo/bar');
+      expect(join('foo', 'bar', '/')).toBe('foo/bar');
+      expect(join('foo', '/', 'bar')).toBe('foo/bar');
+      expect(join('foo', '/', '/', 'bar')).toBe('foo/bar');
       expect(join('..', 'foo', 'bar.ts')).toBe('../foo/bar.ts');
+      expect(join('foo', '..', 'bar.ts')).toBe('bar.ts');
       expect(join('.', 'foo', 'bar.ts')).toBe('foo/bar.ts');
     });