example-test-gen 1.0.0-prerelease-2026-03-31

package/README.md

@@ -0,0 +1,54 @@
+# example-test-gen
+
+Generate test files from `@example` snippets in your code.
+
+[ UNDER CONSTRUCTION ] 2026-03-31 - This package is still being built! Tune in later!
+
+## Contents
+
+- [Overview](#overview)
+- [Requirements](#requirements)
+
+## Overview
+
+`example-test-gen` extracts test code from JSDoc `@example` annotations and generates runnable test files.
+
+## Requirements
+
+These requirements have been rewritten and defined since the core code was initially created.
+When implementing new features or modifying existing ones, please refer to these requirements to ensure compliance.
+
+The existing code should be updated to meet these requirements where applicable.
+
+| ID | Requirement (plain language) | Test Pattern(s) | User Reviewed | Tests Completed |
+|----|------------------------------|-----------------|---------------|-----------|
+| **CLI01** | **CLI Entry**: Executable as `npx example-test-gen` with `--help` and `--version` flags | End-to-end CLI tests via @example in `cli.ts` | [x] | [x] |
+| **CLI02** | **Built-in Configs**: Support `--config=jest` and `--config=vitest` for zero-config test generation | End-to-end CLI tests via @example in `cli.ts` | [x] | [x] |
+| **CLI03** | **Custom Config Path**: Support `--config=./path.mjs` for user-defined config files | End-to-end CLI tests via @example in `cli.ts` | [x] | [x] |
+| **CLI04** | **CLI Error Handling**: Clear error messages for missing config, invalid config paths, and config load failures | End-to-end CLI tests via @example in `cli.ts` | [x] | [x] |
+| **CLI05** | **CLI Files Override**: Support `--files` flag for ad-hoc file selection without config file (e.g., `--files="src/**/*.ts"` or `--files="src/a.ts,src/b.ts"`) | End-to-end CLI tests via @example in `cli.ts` | [x] | [x] |
+| **CLI06** | **CLI Output Directory**: Support `--outDir` flag to override the default output directory (e.g., `--outDir=./generated-tests`) | End-to-end CLI tests via @example in `cli.ts` | [x] | [x] |
+| **SDK01** | **Programmatic API**: Export `generateTests()` function as primary entry point | Contract tests via @example in `index.ts` | [x] | [ ] |
+| **SDK02** | **API Types**: Export TypeScript types (`SnippetInfo`, `MapperResult`, `MapperFn`, `Config`) | Contract tests via @example in `index.ts` | [x] | [ ] |
+| **SDK03** | **Built-in Mappers Export**: Export `jestMapper` and `vitestMapper` for SDK consumers | Contract tests via @example in `builtins.ts` | [x] | [ ] |
+| **SDK04** | **Config Object Support**: Accept `files` (string or string[] with glob support), `mapper` (function or built-in name), and `outDir` (string) | Integration tests via @example in `config.ts` | [x] | [ ] |
+| **SDK05** | **Config Validation**: Validate required fields (`files`, `mapper` or built-in ref) with helpful error messages | Unit tests via @example in `config.ts` | [x] | [ ] |
+| **CORE01** | **Source Discovery**: Find source files from `files` glob(s) (supports `**/*` style paths) | Unit tests via @example in `extractor.ts` | [x] | [ ] |
+| **CORE02** | **@example Extraction**: Extract code snippets from JSDoc `@example` blocks | Unit tests via @example in `extractor.ts` | [x] | [ ] |
+| **CORE03** | **Snippet Parsing**: Parse optional description, code fence language hint, and snippet body | Unit tests via @example in `extractor.ts` | [x] | [ ] |
+| **CORE04** | **Import Extraction**: Identify and separate ES module imports from executable code in snippets | Unit tests via @example in `extractor.ts` | [x] | [ ] |
+| **CORE05** | **Multiple Snippets**: Detect and extract all @example blocks when multiple are present in a single source file | Unit tests via @example in `extractor.ts` | [x] | [ ] |
+| **TRANS01** | **Jest Mapper**: Wrap snippets in `describe`/`it` blocks with Jest-compatible imports | Unit tests via @example in `builtins.ts` | [x] | [ ] |
+| **TRANS02** | **Vitest Mapper**: Wrap snippets in `describe`/`it` blocks with Vitest-compatible imports | Unit tests via @example in `builtins.ts` | [x] | [ ] |
+| **TRANS03** | **Output Header**: Include source file path, description, and auto-generated notice in test file header (remove "Snippet:" section) | Unit tests via @example in `builtins.ts` | [x] | [ ] |
+| **TRANS04** | **Output Structure**: Separate imports section from test body; deduplicate imports | Unit tests via @example in `builtins.ts` | [x] | [ ] |
+| **TRANS05** | **Import Path Transformation**: Rewrite relative imports (`./foo.ts`) to be valid from test file location (`../src/foo.js`) | Unit tests via @example in `builtins.ts` | [x] | [ ] |
+| **TRANS06** | **Output Directory Mirroring**: Write generated tests to `outDir` preserving relative directory structure (`src/foo.ts` → `tests/foo.test.ts`) | Integration tests via @example in `config.ts` | [x] | [ ] |
+| **TRANS07** | **File Overwriting**: Overwrite existing test files without prompting; idempotent generation | Integration tests via @example in `config.ts` | [x] | [ ] |
+| **TRANS08** | **Auto Source Import**: Generated test files automatically import all exports from the source file, removing the need for users to manually import the method-under-test in their @example blocks | Unit tests via @example in `builtins.ts` | [x] | [ ] |
+| **META01** | **Self-Testing**: Library generates and runs its own tests via `@example` annotations (dogfooding) | @example in all source files, generated to `tests/` | [x] | [ ] |
+
+**Requirement Notes:**
+- **TRANS05**: When the Vitest/Jest mapper generates tests in `tests/` directory, it must transform `import { x } from './src/foo.ts'` in the snippet to `import { x } from '../src/foo.js'` (or equivalent) in the output
+- **TRANS06**: Config should support `outDir: 'tests'` which mirrors source structure (`src/foo.ts` → `tests/foo.test.ts`)
+- **SDK05**: Config validation should check required fields (`files`, `mapper` or built-in ref) and provide helpful error messages

package/dist/builtins.d.ts

@@ -0,0 +1,8 @@
+import { MapperFunction } from './types.js';
+export declare function createJestMapper(): MapperFunction;
+export declare function createVitestMapper(): MapperFunction;
+export declare const builtInConfigs: Record<string, {
+    pattern: string | string[];
+    mapper: MapperFunction;
+}>;
+//# sourceMappingURL=builtins.d.ts.map

package/dist/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,wBAAgB,gBAAgB,IAAI,cAAc,CAcjD;AAED,wBAAgB,kBAAkB,IAAI,cAAc,CAcnD;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CASjG,CAAC"}

package/dist/builtins.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.builtInConfigs = void 0;
+exports.createJestMapper = createJestMapper;
+exports.createVitestMapper = createVitestMapper;
+function createJestMapper() {
+    return ({ imports, snippet, description, dir, filename }) => {
+        const testName = filename.replace(/\.(ts|js|tsx|jsx|mjs|cjs)$/, '');
+        const outputDir = dir || '.';
+        const itDescription = description ?? 'example test';
+        const importSection = imports.length > 0 ? imports.join('\n') + '\n\n' : '';
+        const header = `// Generated test from @example snippet\n// Source: ${dir ? dir + '/' : ''}${filename}\n\n`;
+        return {
+            output: `${header}${importSection}describe('${testName}', () => {\n  it('${itDescription}', async () => {\n${snippet.split('\n').map(line => '    ' + line).join('\n')}\n  });\n});`,
+            filepath: `${outputDir}/${testName}.test.js`
+        };
+    };
+}
+function createVitestMapper() {
+    return ({ imports, snippet, description, dir, filename }) => {
+        const testName = filename.replace(/\.(ts|js|tsx|jsx|mjs|cjs)$/, '');
+        const outputDir = dir || '.';
+        const itDescription = description ?? `${testName} example`;
+        const importSection = imports.length > 0 ? imports.join('\n') + '\n\n' : '';
+        const header = `// Generated test from @example snippet\n// Source: ${dir ? dir + '/' : ''}${filename}\n\n`;
+        return {
+            output: `${header}${importSection}import { test, expect } from 'vitest';\n\ntest('${itDescription}', async () => {\n${snippet.split('\n').map(line => '  ' + line).join('\n')}\n});`,
+            filepath: `${outputDir}/${testName}.test.ts`
+        };
+    };
+}
+exports.builtInConfigs = {
+    jest: {
+        pattern: 'src/**/*.{ts,js,tsx,jsx}',
+        mapper: createJestMapper()
+    },
+    vitest: {
+        pattern: 'src/**/*.{ts,js,tsx,jsx}',
+        mapper: createVitestMapper()
+    }
+};
+//# sourceMappingURL=builtins.js.map

package/dist/builtins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.js","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":";;;AAEA,4CAcC;AAED,gDAcC;AA9BD,SAAgB,gBAAgB;IAC9B,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1D,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,4BAA4B,EAAE,EAAE,CAAC,CAAC;QACpE,MAAM,SAAS,GAAG,GAAG,IAAI,GAAG,CAAC;QAC7B,MAAM,aAAa,GAAG,WAAW,IAAI,cAAc,CAAC;QAEpD,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,MAAM,MAAM,GAAG,uDAAuD,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,MAAM,CAAC;QAE5G,OAAO;YACL,MAAM,EAAE,GAAG,MAAM,GAAG,aAAa,aAAa,QAAQ,qBAAqB,aAAa,qBAAqB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc;YACpL,QAAQ,EAAE,GAAG,SAAS,IAAI,QAAQ,UAAU;SAC7C,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,SAAgB,kBAAkB;IAChC,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1D,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,4BAA4B,EAAE,EAAE,CAAC,CAAC;QACpE,MAAM,SAAS,GAAG,GAAG,IAAI,GAAG,CAAC;QAC7B,MAAM,aAAa,GAAG,WAAW,IAAI,GAAG,QAAQ,UAAU,CAAC;QAE3D,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,MAAM,MAAM,GAAG,uDAAuD,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,MAAM,CAAC;QAE5G,OAAO;YACL,MAAM,EAAE,GAAG,MAAM,GAAG,aAAa,mDAAmD,aAAa,qBAAqB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO;YACpL,QAAQ,EAAE,GAAG,SAAS,IAAI,QAAQ,UAAU;SAC7C,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAEY,QAAA,cAAc,GAA2E;IACpG,IAAI,EAAE;QACJ,OAAO,EAAE,0BAA0B;QACnC,MAAM,EAAE,gBAAgB,EAAE;KAC3B;IACD,MAAM,EAAE;QACN,OAAO,EAAE,0BAA0B;QACnC,MAAM,EAAE,kBAAkB,EAAE;KAC7B;CACF,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const url_1 = require("url");
+const generator_js_1 = require("./generator.js");
+const builtins_js_1 = require("./builtins.js");
+async function loadConfig(configPath) {
+    // Check for built-in configs first
+    if (builtins_js_1.builtInConfigs[configPath]) {
+        return builtins_js_1.builtInConfigs[configPath];
+    }
+    const resolvedPath = path_1.default.resolve(configPath);
+    const fileUrl = (0, url_1.pathToFileURL)(resolvedPath).href;
+    const module = await import(fileUrl);
+    return module.default || module;
+}
+/**
+ * CLI entry point for example-test-gen
+ *
+ * @example CLI01_help_flag_shows_usage_info
+ * ```ts
+ * import { runCli, readFile } from './test/helpers/cli.js';
+ * expect(runCli('--help')).toContain(readFile('outputs/help.txt'));
+ * ```
+ *
+ * @example CLI01_version_flag_shows_package_version
+ * ```ts
+ * import { runCli, getPackageVersion } from './test/helpers/cli.js';
+ * const output = runCli('--version').trim();
+ * expect(output).toBe(getPackageVersion());
+ * ```
+ *
+ * @example CLI02_builtin_config_jest_generates_jest_tests
+ * ```ts
+ * import { runCliWith, cleanDir, assertExists } from './test/helpers/cli.js';
+ * cleanDir('generated-tests');
+ * runCliWith({ config: 'jest' });
+ * assertExists('cli.test.js');
+ * ```
+ *
+ * @example CLI02_builtin_config_vitest_generates_vitest_tests
+ * ```ts
+ * import { runCliWith, cleanDir, assertExists } from './test/helpers/cli.js';
+ * cleanDir('tests');
+ * runCliWith({ config: 'vitest' });
+ * assertExists('tests/cli.test.ts');
+ * ```
+ *
+ * @example CLI03_custom_config_path_loads_user_defined_config
+ * ```ts
+ * import { runCliWith, cleanDir, assertExists } from './test/helpers/cli.js';
+ * cleanDir('custom-output');
+ * runCliWith({ config: 'test/fixtures/config/custom.mjs' });
+ * assertExists('custom-output/cli.test.js');
+ * cleanDir('custom-output');
+ * ```
+ *
+ * @example CLI04_missing_config_shows_clear_error
+ * ```ts
+ * import { runCli, expectError } from './test/helpers/cli.js';
+ * const err = expectError(() => runCli('--config=nonexistent-config.mjs'));
+ * expect(err.message).toContain('Error');
+ * ```
+ *
+ * @example CLI04_invalid_config_path_shows_error
+ * ```ts
+ * import { runCli, expectError } from './test/helpers/cli.js';
+ * const err = expectError(() => runCli('--config=/path/that/does/not/exist.mjs'));
+ * expect(err.message).toMatch(/Error|Cannot find module/);
+ * ```
+ *
+ * @example CLI05_files_flag_overrides_config_pattern
+ * ```ts
+ * import { runCliWith, cleanDir, assertExists } from './test/helpers/cli.js';
+ * cleanDir('tests');
+ * runCliWith({ config: 'vitest', files: 'src/cli.ts' });
+ * assertExists('tests/cli.test.ts');
+ * ```
+ *
+ * @example CLI05_files_flag_supports_multiple_patterns
+ * ```ts
+ * import { runCliWith, cleanDir, assertExists } from './test/helpers/cli.js';
+ * cleanDir('tests');
+ * runCliWith({ config: 'vitest', files: 'src/cli.ts,src/index.ts' });
+ * assertExists('tests/cli.test.ts');
+ * assertExists('tests/index.test.ts');
+ * ```
+ *
+ * @example CLI06_outDir_flag_overrides_default_output_directory
+ * ```ts
+ * import { runCliWith, cleanDir, assertExists } from '../test/helpers/cli.js';
+ * cleanDir('my-custom-tests');
+ * runCliWith({ config: 'vitest', outDir: 'my-custom-tests' });
+ * assertExists('my-custom-tests/cli.test.ts');
+ * cleanDir('my-custom-tests');
+ * ```
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    const configFlag = args.find((arg) => arg.startsWith('--config='));
+    const configPath = configFlag ? configFlag.replace('--config=', '') : 'example-test-gen.config.mjs';
+    try {
+        const { mapper, pattern } = await loadConfig(configPath);
+        await (0, generator_js_1.generate)({ pattern, mapper });
+        console.log('Test files generated successfully');
+    }
+    catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;AACA,gDAAwB;AACxB,6BAAoC;AACpC,iDAA0C;AAE1C,+CAA+C;AAE/C,KAAK,UAAU,UAAU,CAAC,UAAkB;IAC1C,mCAAmC;IACnC,IAAI,4BAAc,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,4BAAc,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,YAAY,GAAG,cAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAA,mBAAa,EAAC,YAAY,CAAC,CAAC,IAAI,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3E,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,6BAA6B,CAAC;IAEpG,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,CAAC;QACzD,MAAM,IAAA,uBAAQ,EAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;QAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":""}

package/dist/config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":""}

package/dist/extractor.d.ts

@@ -0,0 +1,25 @@
+import { SnippetInfo } from './types.js';
+/**
+ * Extracts @example code snippets from a file
+ * @example extracts snippets correctly
+ * ```ts
+ * import { extractSnippets } from './extractor.ts';
+ *
+ * // Interestingly, the extractor.ts path we provide to extractSnippets
+ * // is different from the path we use in the import statement.
+ * // This is because extractSnippets expects a project-relative path,
+ * // while the import statement depends on the test file's location
+ * // relative to this file.
+ *
+ * const snippets = await extractSnippets('./src/extractor.ts', process.cwd());
+ * expect(snippets[0].description).toBe('extracts snippets correctly');
+ * expect(snippets[0].filename).toBe('extractor.ts');
+ * expect(snippets[0].dir).toBe('src');
+ *
+ * // FOOBARBAZBAT <-- should be in the snippet, since I wrote it here.
+ * expect(snippets[0].snippet).toContain('FOOBARBAZBAT');
+ * ```
+ */
+export declare function extractSnippets(filePath: string, cwd: string): Promise<SnippetInfo[]>;
+export declare function findFiles(patterns: string | string[], cwd: string): AsyncGenerator<string>;
+//# sourceMappingURL=extractor.d.ts.map

package/dist/extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../src/extractor.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAIzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,WAAW,EAAE,CAAC,CAoCxB;AAED,wBAAuB,SAAS,CAC9B,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAC3B,GAAG,EAAE,MAAM,GACV,cAAc,CAAC,MAAM,CAAC,CAMxB"}

package/dist/extractor.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSnippets = extractSnippets;
+exports.findFiles = findFiles;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const EXAMPLE_REGEX = /@example(?:\s+([^\n`]+))?\s*\n?\s*(?:\*\s*)?```[a-z]*\n?([\s\S]*?)```/g;
+/**
+ * Extracts @example code snippets from a file
+ * @example extracts snippets correctly
+ * ```ts
+ * import { extractSnippets } from './extractor.ts';
+ *
+ * // Interestingly, the extractor.ts path we provide to extractSnippets
+ * // is different from the path we use in the import statement.
+ * // This is because extractSnippets expects a project-relative path,
+ * // while the import statement depends on the test file's location
+ * // relative to this file.
+ *
+ * const snippets = await extractSnippets('./src/extractor.ts', process.cwd());
+ * expect(snippets[0].description).toBe('extracts snippets correctly');
+ * expect(snippets[0].filename).toBe('extractor.ts');
+ * expect(snippets[0].dir).toBe('src');
+ *
+ * // FOOBARBAZBAT <-- should be in the snippet, since I wrote it here.
+ * expect(snippets[0].snippet).toContain('FOOBARBAZBAT');
+ * ```
+ */
+async function extractSnippets(filePath, cwd) {
+    const content = await fs_1.promises.readFile(filePath, 'utf-8');
+    const dir = path_1.default.dirname(path_1.default.relative(cwd, filePath));
+    const filename = path_1.default.basename(filePath);
+    const snippets = [];
+    let match;
+    while ((match = EXAMPLE_REGEX.exec(content)) !== null) {
+        const description = match[1]?.trim() ?? null;
+        const rawSnippet = match[2].trim();
+        // Strip JSDoc comment prefixes from each line
+        const cleanedSnippet = rawSnippet
+            .split('\n')
+            .map(line => line.replace(/^\s*\*\s?/, ''))
+            .join('\n');
+        // Separate import statements from the rest of the snippet
+        const lines = cleanedSnippet.split('\n');
+        const imports = [];
+        const codeLines = [];
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith('import ') || trimmed.startsWith('require(')) {
+                imports.push(line);
+            }
+            else {
+                codeLines.push(line);
+            }
+        }
+        const snippet = codeLines.join('\n').trim();
+        snippets.push({ imports, snippet, description, dir, filename });
+    }
+    return snippets;
+}
+async function* findFiles(patterns, cwd) {
+    const fg = await import('fast-glob');
+    const files = await fg.default(patterns, { cwd, absolute: true });
+    for (const file of files) {
+        yield file;
+    }
+}
+//# sourceMappingURL=extractor.js.map

package/dist/extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.js","sourceRoot":"","sources":["../src/extractor.ts"],"names":[],"mappings":";;;;;AA2BA,0CAuCC;AAED,8BASC;AA7ED,2BAAoC;AACpC,gDAAwB;AAGxB,MAAM,aAAa,GAAG,wEAAwE,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;GAoBG;AACI,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,GAAW;IAEX,MAAM,OAAO,GAAG,MAAM,aAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,cAAI,CAAC,OAAO,CAAC,cAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,cAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEzC,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,IAAI,KAA6B,CAAC;IAElC,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACtD,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;QAC7C,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACnC,8CAA8C;QAC9C,MAAM,cAAc,GAAG,UAAU;aAC9B,KAAK,CAAC,IAAI,CAAC;aACX,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;aAC1C,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,0DAA0D;QAC1D,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAa,EAAE,CAAC;QAE/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBACpE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAEM,KAAK,SAAS,CAAC,CAAC,SAAS,CAC9B,QAA2B,EAC3B,GAAW;IAEX,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/generator.d.ts

@@ -0,0 +1,3 @@
+import { GenerateOptions } from './types.js';
+export declare function generate(options: GenerateOptions): Promise<void>;
+//# sourceMappingURL=generator.d.ts.map

package/dist/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAC;AAG3D,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBtE"}

package/dist/generator.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generate = generate;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const extractor_js_1 = require("./extractor.js");
+async function generate(options) {
+    const { pattern, mapper, cwd = process.cwd() } = options;
+    for await (const filePath of (0, extractor_js_1.findFiles)(pattern, cwd)) {
+        const snippets = await (0, extractor_js_1.extractSnippets)(filePath, cwd);
+        for (const snippetInfo of snippets) {
+            const result = await mapper(snippetInfo);
+            if (!result)
+                continue;
+            const { output, filepath: relativeOutputPath } = result;
+            const absoluteOutputPath = path_1.default.resolve(cwd, relativeOutputPath);
+            const outputDir = path_1.default.dirname(absoluteOutputPath);
+            await fs_1.promises.mkdir(outputDir, { recursive: true });
+            await fs_1.promises.writeFile(absoluteOutputPath, output, 'utf-8');
+        }
+    }
+}
+//# sourceMappingURL=generator.js.map

package/dist/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":";;;;;AAKA,4BAmBC;AAxBD,2BAAoC;AACpC,gDAAwB;AAExB,iDAA4D;AAErD,KAAK,UAAU,QAAQ,CAAC,OAAwB;IACrD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAEzD,IAAI,KAAK,EAAE,MAAM,QAAQ,IAAI,IAAA,wBAAS,EAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;QACrD,MAAM,QAAQ,GAAG,MAAM,IAAA,8BAAe,EAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAEtD,KAAK,MAAM,WAAW,IAAI,QAAQ,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;YAEzC,IAAI,CAAC,MAAM;gBAAE,SAAS;YAEtB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAAC;YACxD,MAAM,kBAAkB,GAAG,cAAI,CAAC,OAAO,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;YACjE,MAAM,SAAS,GAAG,cAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;YAEnD,MAAM,aAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/C,MAAM,aAAE,CAAC,SAAS,CAAC,kBAAkB,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { MapperFunction } from './types.js';
+export { generate } from './generator.js';
+export { GenerateOptions, MapperFunction, MapperResult, SnippetInfo } from './types.js';
+export { createJestMapper, createVitestMapper, builtInConfigs } from './builtins.js';
+export declare function generateTests(pattern: string | string[], mapper: MapperFunction, cwd?: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAErF,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAC1B,MAAM,EAAE,cAAc,EACtB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.builtInConfigs = exports.createVitestMapper = exports.createJestMapper = exports.generate = void 0;
+exports.generateTests = generateTests;
+const generator_js_1 = require("./generator.js");
+var generator_js_2 = require("./generator.js");
+Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return generator_js_2.generate; } });
+var builtins_js_1 = require("./builtins.js");
+Object.defineProperty(exports, "createJestMapper", { enumerable: true, get: function () { return builtins_js_1.createJestMapper; } });
+Object.defineProperty(exports, "createVitestMapper", { enumerable: true, get: function () { return builtins_js_1.createVitestMapper; } });
+Object.defineProperty(exports, "builtInConfigs", { enumerable: true, get: function () { return builtins_js_1.builtInConfigs; } });
+async function generateTests(pattern, mapper, cwd) {
+    return (0, generator_js_1.generate)({ pattern, mapper, cwd });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAOA,sCAMC;AAbD,iDAA0C;AAG1C,+CAA0C;AAAjC,wGAAA,QAAQ,OAAA;AAEjB,6CAAqF;AAA5E,+GAAA,gBAAgB,OAAA;AAAE,iHAAA,kBAAkB,OAAA;AAAE,6GAAA,cAAc,OAAA;AAEtD,KAAK,UAAU,aAAa,CACjC,OAA0B,EAC1B,MAAsB,EACtB,GAAY;IAEZ,OAAO,IAAA,uBAAQ,EAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;AAC5C,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export interface SnippetInfo {
+    imports: string[];
+    snippet: string;
+    description: string | null;
+    dir: string;
+    filename: string;
+}
+export interface MapperResult {
+    output: string;
+    filepath: string;
+}
+export type MapperFunction = (info: SnippetInfo) => MapperResult | null | Promise<MapperResult | null>;
+export interface GenerateOptions {
+    pattern: string | string[];
+    mapper: MapperFunction;
+    cwd?: string;
+    /** Output directory for generated tests (default: 'tests') */
+    outDir?: string;
+}
+/** @deprecated Use GenerateOptions instead - maintained for backwards compatibility */
+export type Config = GenerateOptions;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;AAEvG,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,uFAAuF;AACvF,MAAM,MAAM,MAAM,GAAG,eAAe,CAAC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "example-test-gen",
+  "version": "1.0.0-prerelease-2026-03-31",
+  "description": "Generate test files from @example snippets in your code",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "example-test-gen": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "pretest": "npx example-test-gen --config=vitest",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "test",
+    "example",
+    "jsdoc",
+    "generate",
+    "snippet"
+  ],
+  "files": [
+    "dist/"
+  ],
+  "dependencies": {
+    "fast-glob": "^3.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}