fix(cli): --stats accepts optional path string as per documentation (#6524)

Co-authored-by: John Jenkins <john.jenkins@nanoporetech.com>

Author: johnjenkins

src/cli/config-flags.ts

@@ -29,7 +29,6 @@ export const BOOLEAN_CLI_FLAGS = [
   'skipNodeCheck',
   'spec',
   'ssr',
-  'stats',
   'updateScreenshot',
   'verbose',
   'version',
@@ -181,6 +180,12 @@ export const BOOLEAN_STRING_CLI_FLAGS = [
    * {@see https://developer.chrome.com/blog/chrome-headless-shell/}
    */
   'headless',
+  /**
+   * `stats` is an argument that can optionally accept a file path where stats should be written.
+   * When used as a boolean (--stats), it defaults to 'stencil-stats.json'.
+   * When used with a path (--stats dist/stats.json), it writes to that path.
+   */
+  'stats',
 ] as const;
 
 /**

src/cli/task-help.ts

@@ -23,7 +23,7 @@ export const taskHelp = async (flags: ConfigFlags, logger: d.Logger, sys: d.Comp
       ${logger.cyan('--prerender')} ${logger.dim('.......')} Prerender the application
       ${logger.cyan('--docs')} ${logger.dim('............')} Generate component readme.md docs
       ${logger.cyan('--config')} ${logger.dim('..........')} Set stencil config file
-      ${logger.cyan('--stats')} ${logger.dim('...........')} Write stencil-stats.json file
+      ${logger.cyan('--stats')} ${logger.dim('...........')} Write stats, optional file path (default: stencil-stats.json)
       ${logger.cyan('--log')} ${logger.dim('.............')} Write stencil-build.log file
       ${logger.cyan('--debug')} ${logger.dim('...........')} Set the log level to debug
 

src/cli/test/parse-flags.spec.ts

@@ -144,14 +144,14 @@ describe('parseFlags', () => {
     it('parses a boolean-string flag as a boolean with no arg', () => {
       const args = [`--${cliArg}`];
       const flags = parseFlags(args);
-      expect(flags.headless).toBe(true);
+      expect(flags[cliArg]).toBe(true);
       expect(flags.knownArgs).toEqual([`--${cliArg}`]);
     });
 
     it(`parses a boolean-string flag as a falsy boolean with "no" arg - --no-${cliArg}`, () => {
       const args = [`--no-${cliArg}`];
       const flags = parseFlags(args);
-      expect(flags.headless).toBe(false);
+      expect(flags[cliArg]).toBe(false);
       expect(flags.knownArgs).toEqual([`--no-${cliArg}`]);
     });
 
@@ -160,21 +160,21 @@ describe('parseFlags', () => {
     }`, () => {
       const negativeFlag = '--no' + cliArg.charAt(0).toUpperCase() + cliArg.slice(1);
       const flags = parseFlags([negativeFlag]);
-      expect(flags.headless).toBe(false);
+      expect(flags[cliArg]).toBe(false);
       expect(flags.knownArgs).toEqual([negativeFlag]);
     });
 
     it('parses a boolean-string flag as a string with a string arg', () => {
       const args = [`--${cliArg}`, 'shell'];
       const flags = parseFlags(args);
-      expect(flags.headless).toBe('shell');
-      expect(flags.knownArgs).toEqual(['--headless', 'shell']);
+      expect(flags[cliArg]).toBe('shell');
+      expect(flags.knownArgs).toEqual([`--${cliArg}`, 'shell']);
     });
 
     it('parses a boolean-string flag as a string with a string arg using equality', () => {
       const args = [`--${cliArg}=shell`];
       const flags = parseFlags(args);
-      expect(flags.headless).toBe('shell');
+      expect(flags[cliArg]).toBe('shell');
       expect(flags.knownArgs).toEqual([`--${cliArg}`, 'shell']);
     });
   });

src/compiler/config/outputs/validate-stats.ts

@@ -9,9 +9,16 @@ export const validateStats = (userConfig: d.ValidatedConfig, userOutputs: d.Outp
   if (userConfig.flags.stats) {
     const hasOutputTarget = userOutputs.some(isOutputTargetStats);
     if (!hasOutputTarget) {
-      outputTargets.push({
+      const statsOutput: d.OutputTargetStats = {
         type: STATS,
-      });
+      };
+
+      // If --stats was provided with a path (string), use it; otherwise use default
+      if (typeof userConfig.flags.stats === 'string') {
+        statsOutput.file = userConfig.flags.stats;
+      }
+
+      outputTargets.push(statsOutput);
     }
   }
 

src/compiler/config/test/validate-stats.spec.ts

@@ -50,4 +50,51 @@ describe('validateStats', () => {
     const { config } = validateConfig(userConfig, mockLoadConfigInit());
     expect(config.outputTargets.some((o) => o.type === 'stats')).toBe(false);
   });
+
+  it('adds stats from flags with custom path string', () => {
+    // Test --stats dist/stats.json behavior
+    userConfig.flags!.stats = 'dist/custom-stats.json';
+
+    const { config } = validateConfig(userConfig, mockLoadConfigInit());
+    const o = config.outputTargets.find((o) => o.type === 'stats') as d.OutputTargetStats;
+    expect(o).toBeDefined();
+    expect(o.file).toContain('dist/custom-stats.json');
+  });
+
+  it('adds stats from flags with custom path (absolute)', () => {
+    // Test --stats /tmp/stats.json behavior
+    userConfig.flags!.stats = '/tmp/absolute-stats.json';
+
+    const { config } = validateConfig(userConfig, mockLoadConfigInit());
+    const o = config.outputTargets.find((o) => o.type === 'stats') as d.OutputTargetStats;
+    expect(o).toBeDefined();
+    expect(o.file).toBe('/tmp/absolute-stats.json');
+  });
+
+  it('flags stats path takes precedence over default when no outputTarget', () => {
+    // When --stats has a path, it should be used instead of the default
+    userConfig.flags!.stats = 'custom-location/stats.json';
+
+    const { config } = validateConfig(userConfig, mockLoadConfigInit());
+    const o = config.outputTargets.find((o) => o.type === 'stats') as d.OutputTargetStats;
+    expect(o).toBeDefined();
+    expect(o.file).toContain('custom-location/stats.json');
+    expect(o.file).not.toContain('stencil-stats.json');
+  });
+
+  it('does not override existing stats outputTarget when flag has path', () => {
+    // When there's already a stats outputTarget in config, flag should not add another
+    userConfig.outputTargets = [
+      {
+        type: 'stats',
+        file: 'config-defined.json',
+      } as d.OutputTargetStats,
+    ];
+    userConfig.flags!.stats = 'flag-defined.json';
+
+    const { config } = validateConfig(userConfig, mockLoadConfigInit());
+    const statsTargets = config.outputTargets.filter((o) => o.type === 'stats');
+    expect(statsTargets.length).toBe(1);
+    expect(statsTargets[0].file).toContain('config-defined.json');
+  });
 });