feat: support dynamic coverage flag

README.md

@@ -27,7 +27,9 @@ Enjoying **Poku**? [Give him a star to show your support](https://github.com/wel
 npm i -D @pokujs/c8
 ```
 
-### Enable the Plugin
+### Usage
+
+#### Enable the Plugin
 
 ```js
 // poku.config.js
@@ -39,7 +41,7 @@ export default defineConfig({
 });
 ```
 
-That's it! Run `poku` and a coverage summary will be printed after your test results.
+Run `poku` and a coverage summary will be printed after your test results.
 
 > [!IMPORTANT]
 >
@@ -51,6 +53,9 @@ That's it! Run `poku` and a coverage summary will be printed after your test res
 
 ```js
 coverage({
+  // Activation
+  requireFlag: true, // default: false
+
   // Reporters
   reporter: ['text', 'lcov'], // default: ['text']
 
@@ -141,6 +146,25 @@ coverage({
 });
 ```
 
+### Require `--coverage` flag
+
+By default, coverage runs whenever the plugin is active. Use `requireFlag` to only collect coverage when `--coverage` is passed to the CLI, keeping watch mode, debugging, and filtered runs fast:
+
+```js
+coverage({
+  include: ['src/**'],
+  requireFlag: true,
+});
+```
+
+```bash
+# No coverage (plugin is a no-op)
+poku test/
+
+# With coverage
+poku --coverage test/
+```
+
 ### Extending Monocart reporters
 
 ```bash

src/index.ts

@@ -10,6 +10,7 @@ export type { CoverageOptions } from './types.js';
 export const coverage = (
   options: CoverageOptions = Object.create(null)
 ): PokuPlugin => {
+  let enabled = false;
   let tempDir: string;
   let originalEnv: string | undefined;
   let userProvidedTempDir: boolean;
@@ -18,6 +19,9 @@ export const coverage = (
     name: '@pokujs/c8',
 
     setup(context) {
+      if (options.requireFlag && !process.argv.includes('--coverage')) return;
+      enabled = true;
+
       if (context.runtime !== 'node')
         console.warn(
           `[@pokujs/c8] V8 coverage is only supported on Node.js (current runtime: ${context.runtime}). Coverage data may not be collected.`
@@ -44,6 +48,8 @@ export const coverage = (
     },
 
     async teardown(context) {
+      if (!enabled) return;
+
       if (originalEnv !== undefined) process.env.NODE_V8_COVERAGE = originalEnv;
       else delete process.env.NODE_V8_COVERAGE;
 

src/types.ts

@@ -31,6 +31,16 @@ type KnownExtension =
 type Extension = KnownExtension | (string & NonNullable<unknown>);
 
 export type CoverageOptions = {
+  /**
+   * Require the `--coverage` CLI flag to activate coverage collection.
+   *
+   * When `true`, coverage only runs if `--coverage` is passed to the CLI.
+   * When `false`, coverage runs whenever the plugin is active.
+   *
+   * @default false
+   */
+  requireFlag?: boolean;
+
   /** Coverage reporters to use. */
   reporter?: Reporter | Reporter[];
 

test/__fixtures__/e2e/configs/require-flag.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'poku';
+import { coverage } from '../../../../src/index.ts';
+
+export default defineConfig({
+  include: ['test/'],
+  plugins: [
+    coverage({
+      include: ['src/**'],
+      reporter: ['text'],
+      requireFlag: true,
+    }),
+  ],
+});

test/e2e/coverage-require-flag.test.ts

@@ -0,0 +1,31 @@
+import { assert, test } from 'poku';
+import { inspectPoku } from 'poku/plugins';
+
+const fixtureDir = 'test/__fixtures__/e2e';
+const pokuBin = 'node_modules/poku/lib/bin/index.js';
+
+test('coverage is skipped without --coverage flag when requireFlag is true', async () => {
+  const result = await inspectPoku({
+    command: '-c=configs/require-flag.config.ts',
+    spawnOptions: { cwd: fixtureDir },
+    bin: pokuBin,
+  });
+
+  assert.strictEqual(result.exitCode, 0);
+  assert(
+    !result.stdout.includes('%'),
+    'coverage report should not be generated'
+  );
+});
+
+test('coverage runs with --coverage flag when requireFlag is true', async () => {
+  const result = await inspectPoku({
+    command: '--coverage -c=configs/require-flag.config.ts',
+    spawnOptions: { cwd: fixtureDir },
+    bin: pokuBin,
+  });
+
+  assert.strictEqual(result.exitCode, 0);
+  assert(result.stdout.includes('math.ts'));
+  assert(result.stdout.includes('%'));
+});