fix(compiler): re-enable build caching (#4503)

* fix(cache): port george-payne pr to v4

* update where build caching is written

* fix JsDoc

* remove `enableCacheStats` config flag

* consistent language

---------

Co-authored-by: Ryan Waskiewicz <ryanwaskiewicz@gmail.com>

BREAKING_CHANGES.md

@@ -15,6 +15,7 @@ This is a comprehensive list of the breaking changes introduced in the major ver
   - [In Browser Compilation Support Removed](#in-browser-compilation-support-removed)
   - [Legacy Context and Connect APIs Removed](#legacy-context-and-connect-APIs-removed)
   - [Legacy Browser Support Removed](#legacy-browser-support-removed)
+  - [Legacy Cache Stats Config Flag Removed](#legacy-cache-stats-config-flag-removed)
   - [Drop Node 14 Support](#drop-node-14-support)
 
 ### General
@@ -69,6 +70,11 @@ DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DO
 was needed in the current browser, and include one if so.
 This field should be removed from a project's Stencil configuration file (`stencil.config.ts`). 
 
+### Legacy Cache Stats Config Flag Removed
+
+The `enableCacheStats` flag was used in legacy behavior for caching, but has not been used for some time. This
+flag has been removed from Stencil's API and should be removed from a project's Stencil configuration file (`stencil.config.ts`).
+
 ### Drop Node 14 Support
 
 Stencil no longer supports Node 14.

src/compiler/build/write-build.ts

@@ -32,7 +32,9 @@ export const writeBuild = async (
 
     // successful write
     // kick off writing the cached file stuff
+    await compilerCtx.cache.commit();
     buildCtx.debug(`in-memory-fs: ${compilerCtx.fs.getMemoryStats()}`);
+    buildCtx.debug(`cache: ${compilerCtx.cache.getMemoryStats()}`);
 
     await outputServiceWorkers(config, buildCtx);
     await validateBuildFiles(config, compilerCtx, buildCtx);

src/compiler/cache.ts

@@ -8,6 +8,7 @@ export class Cache implements d.Cache {
   private skip = false;
   private sys: d.CompilerSystem;
   private logger: d.Logger;
+  private buildCacheDir: string;
 
   constructor(private config: d.Config, private cacheFs: InMemoryFileSystem) {
     this.sys = config.sys;
@@ -19,16 +20,18 @@ export class Cache implements d.Cache {
       return;
     }
 
+    this.buildCacheDir = join(this.config.cacheDir, '.build');
+
     if (!this.config.enableCache || !this.cacheFs) {
       this.config.logger.info(`cache optimizations disabled`);
       this.clearDiskCache();
       return;
     }
 
-    this.config.logger.debug(`cache enabled, cacheDir: ${this.config.cacheDir}`);
+    this.config.logger.debug(`cache enabled, cacheDir: ${this.buildCacheDir}`);
 
     try {
-      const readmeFilePath = join(this.config.cacheDir, '_README.log');
+      const readmeFilePath = join(this.buildCacheDir, '_README.log');
       await this.cacheFs.writeFile(readmeFilePath, CACHE_DIR_README);
     } catch (e) {
       this.logger.error(`Cache, initCacheDir: ${e}`);
@@ -44,7 +47,7 @@ export class Cache implements d.Cache {
     if (this.failed >= MAX_FAILED) {
       if (!this.skip) {
         this.skip = true;
-        this.logger.debug(`cache had ${this.failed} failed ops, skip disk ops for remander of build`);
+        this.logger.debug(`cache had ${this.failed} failed ops, skip disk ops for remainder of build`);
       }
       return null;
     }
@@ -54,7 +57,7 @@ export class Cache implements d.Cache {
       result = await this.cacheFs.readFile(this.getCacheFilePath(key));
       this.failed = 0;
       this.skip = false;
-    } catch (e) {
+    } catch (e: unknown) {
       this.failed++;
       result = null;
     }
@@ -72,7 +75,7 @@ export class Cache implements d.Cache {
     try {
       await this.cacheFs.writeFile(this.getCacheFilePath(key), value);
       result = true;
-    } catch (e) {
+    } catch (e: unknown) {
       this.failed++;
       result = false;
     }
@@ -123,8 +126,8 @@ export class Cache implements d.Cache {
       }
 
       const fs = this.cacheFs.sys;
-      const cachedFileNames = await fs.readDir(this.config.cacheDir);
-      const cachedFilePaths = cachedFileNames.map((f) => join(this.config.cacheDir, f));
+      const cachedFileNames = await fs.readDir(this.buildCacheDir);
+      const cachedFilePaths = cachedFileNames.map((f) => join(this.buildCacheDir, f));
 
       let totalCleared = 0;
 
@@ -150,16 +153,16 @@ export class Cache implements d.Cache {
 
   async clearDiskCache() {
     if (this.cacheFs != null) {
-      const hasAccess = await this.cacheFs.access(this.config.cacheDir);
+      const hasAccess = await this.cacheFs.access(this.buildCacheDir);
       if (hasAccess) {
-        await this.cacheFs.remove(this.config.cacheDir);
+        await this.cacheFs.remove(this.buildCacheDir);
         await this.cacheFs.commit();
       }
     }
   }
 
   private getCacheFilePath(key: string) {
-    return join(this.config.cacheDir, key) + '.log';
+    return join(this.buildCacheDir, key) + '.log';
   }
 
   getMemoryStats() {

src/declarations/stencil-public-compiler.ts

@@ -42,6 +42,36 @@ export interface StencilConfig {
    * To disable this feature, set enableCache to false.
    */
   enableCache?: boolean;
+  /**
+   * The directory where sub-directories will be created for caching when `enableCache` is set
+   * `true` or if using Stencil's Screenshot Connector.
+   *
+   * @default '.stencil'
+   *
+   * @example
+   *
+   * A Stencil config like the following:
+   * ```ts
+   * export const config = {
+   *  ...,
+   *  enableCache: true,
+   *  cacheDir: '.cache',
+   *  testing: {
+   *    screenshotConnector: 'connector.js'
+   *  }
+   * }
+   * ```
+   *
+   * Will result in the following file structure:
+   * ```tree
+   * stencil-project-root
+   * └── .cache
+   *     ├── .build <-- Where build related file caching is written
+   *     |
+   *     └── screenshot-cache.json <-- Where screenshot caching is written
+   * ```
+   */
+  cacheDir?: string;
 
   /**
    * Stencil is traditionally used to compile many components into an app,
@@ -244,10 +274,8 @@ export interface StencilConfig {
   entryComponentsHint?: string[];
   buildDist?: boolean;
   buildLogFilePath?: string;
-  cacheDir?: string;
   devInspector?: boolean;
   devServer?: StencilDevServerConfig;
-  enableCacheStats?: boolean;
   sys?: CompilerSystem;
   tsconfig?: string;
   validateTypes?: boolean;

src/screenshot/connector-base.ts

@@ -42,8 +42,8 @@ export class ScreenshotConnector implements d.ScreenshotConnector {
     this.buildAuthor = opts.buildAuthor;
     this.buildUrl = opts.buildUrl;
     this.previewUrl = opts.previewUrl;
-    (this.buildTimestamp = typeof opts.buildTimestamp === 'number' ? opts.buildTimestamp : Date.now()),
-      (this.cacheDir = opts.cacheDir);
+    this.buildTimestamp = typeof opts.buildTimestamp === 'number' ? opts.buildTimestamp : Date.now();
+    this.cacheDir = opts.cacheDir;
     this.packageDir = opts.packageDir;
     this.rootDir = opts.rootDir;
     this.appNamespace = opts.appNamespace;