What is the current behavior?

See 'New Behavior' section

What is the new behavior?

this patch ensures that paths are properly normalized by the compiler.
this ensures that regardless of the platform (operating system) that a
project is compiled on, paths are uniformly treated internally by
stencil. this has system-wide reaching effects - from the in-memory
filesystem, to configuration/output target validation, and file
generation.

previously, stencil's in-browser compilation support included a polyfill
for the following NodeJS path module functions: join, normalize,
relative & resolve. this polyfill did the following:

• it wrapped each of the aforementioned functions in a normalizePath
  function to convert Windows-style path separators (\\) to
  Unix/POSIX-style path separators (/)
• it overwrote the standard NodeJS path implementations for each of
  these functions.

as a result, calling join or any of the other three methods, even when
importing the method from path like below would result in the polyfill
being called:

import { join } from 'path'; // this imports the polyfilled `join`

// runs the native `path.join`, then normalizes the returned path
const filePath = join(part1, part2);

while this was 'nice' in that stencil engineers didn't need to think
about which implementation of path functions they were using, this
polyfill made some behavior of the compiler hard to understand.

the polyfills were removed in #4317 (b042d8b). this led to calls to the
aforementioned functions to call their original implementations, rather
than the wrapped implementations:

import { join } from 'path'; // imports Node's `join`

// run the native `path.join`, without any normalization
const filePath = join(part1, part2);

discrepencies arose where parts of the code would explicitly wrap a
call to join() (or one of its ilk) around a path normalization
function. this caused paths to not be uniformly normalized throughout
the codebase, leading to errors.

since the removal of in-browser compilation, additional pull requests
to fix path-related issues on windows have landed in the codebase:

• fix(output-targets): fix path normalization logic #4545 (cd58d9c)
• fix(compiler): persist polyfills on build #4932 (b97dadc)

this commit builds on the previous commits by attempting to move
stencil's compiler completely over to polyfilled versions of the
mentioned path functions that are explicitly imported/called.

Does this introduce a breaking change?

• Yes
• No

Testing

A dev build of Stencil containing the changes in this commit was built, and is available under @stencil/core@4.7.1-dev.1699535671.a4c3950

Reproduction cases for the issues that this pull requests closes have been combined into a single repository/reproduction case. This reproduction project can be found here. It uses the aforementioned dev build of Stencil.

The following sections assume that the reproduction repo linked above has been cloned locally and dependencies installed (npm ci). Note that manual testing should occur on a Windows based machine.

Copy Tasks

GitHub Issue: #4980

1. Start the dev server of the reproduction case with npm start
2. Observe the contents of src/dev/worksonmymachine.html have been copied to www/dev/worksonmymachine.html (open the both to confirm that they match).
3. Edit src/dev/worksonmymachine.html - add text, write a blog, add non-sense - whatever feels right. We only need one character of difference here.
4. Open www/dev/worksonmymachine.html, observe your changes made to src/dev/worksonmymachine.html have been propagated to the copied file under www/dev/

Global Styles

GitHub Issue: #4961

1. Start the dev server of the reproduction case with npm start
2. Observe that the background of the 'Hello World' message is blue. This is controlled by a CSS variable that is defined in a global style for the project.
3. In your favorite (or least favorite) text editor, open src/global.css. This file contains the CSS variable that is currently set to blue.
4. Modify the value to be a valid CSS color (red, green, etc.)
5. Observe the background of the 'Hello World' message now properly changes to reflect the changes found in that global CSS file.

CacheDir

The cache directory setting (cacheDir) is now unconditionally normalized.
Previously, absolute paths would not get transformed.
To evaluate this, update the project's stencil.config.ts as follows:

--- a/stencil.config.ts  
+++ b/stencil.config.ts  
@@ -3,6 +3,7 @@ import { Config } from '@stencil/core';  
 export const config: Config = {  
   namespace: 'path-test',  
   globalStyle: 'src/global.css',  
+  cacheDir: 'ABSOLUTE_PATH_TO_THIS_PROJECT\\.stencil',

Running the build npm run build should result in cached files being placed in a .stencil directory in this project's root.

Test Paths

Some test cases associated with validate-testing were updated in the associated pull request/dev build. These changes are believed to be correct/validated by running npm t in the reproduction repository (and are equally exercised by Stencil's CI) - specifically, these ensure that the Jest infrastructure is found on disk and loaded properly. If it weren't tests would fall over/fail!

Ionic Framework

For additional testing, a one-off build of the Ionic Framework "Stencil Nightly Build" with the aforementioned dev build related to this PR was run and passed

Other information

Some of the changes found herein were created/validated using Alice's
codemod branch, #4996
Co-authored-by: alicewriteswrongs alicewriteswrongs@users.noreply.github.com

STENCIL-975 Determine Scope of Path Polyfill Bug, Fix

Fixes: #4980
Fixes: #4961

Spun Off: #5036, #5032, #5029