@gnapi/cotester 1.2.5 → 1.2.7

package/dist/fileWorker.js

@@ -13,6 +13,7 @@ const astCache_1 = require("./astCache");
 const scenarioEngine_1 = require("./scenarioEngine");
 const mockGenerator_1 = require("./mockGenerator");
 const generator_1 = require("./generator");
+const auditLogger_1 = require("./auditLogger");
 const { filePath, projectRoot, config } = worker_threads_1.workerData;
 (async () => {
     try {
@@ -23,7 +24,11 @@ const { filePath, projectRoot, config } = worker_threads_1.workerData;
         }
         const scenarios = (0, scenarioEngine_1.generateScenarios)(functions, config, projectRoot);
         const mockResult = await (0, mockGenerator_1.generateMockFile)(filePath, scenarios, projectRoot, config.srcDir, config.mockDir);
-        await (0, generator_1.generateTestFile)(filePath, scenarios, projectRoot, config.srcDir, config.testDir, mockResult, config.scenarioRules.tableThreshold);
+        const genResult = await (0, generator_1.generateTestFile)(filePath, scenarios, projectRoot, config.srcDir, config.testDir, mockResult, config.scenarioRules.tableThreshold);
+        if (genResult) {
+            const entry = (0, auditLogger_1.buildAuditEntry)(filePath, projectRoot, genResult.added, genResult.merged, genResult.skipped);
+            (0, auditLogger_1.writeAuditEntry)(entry, projectRoot);
+        }
         worker_threads_1.parentPort?.postMessage({ ok: true });
     }
     catch (err) {

package/dist/fileWorker.js.map

@@ -1 +1 @@
-{"version":3,"file":"fileWorker.js","sourceRoot":"","sources":["../src/fileWorker.ts"],"names":[],"mappings":";;AAAA;;;;;;;GAOG;AACH,mDAAwD;AACxD,yCAA+C;AAC/C,qDAAqD;AACrD,mDAAmD;AACnD,2CAA+C;AAc/C,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,2BAAyB,CAAC;AAEpE,CAAC,KAAK,IAAI,EAAE;IACV,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,IAAA,4BAAiB,EAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAE3D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,2BAAU,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,IAAI,EAAyB,CAAC,CAAC;YAC7D,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,IAAA,kCAAiB,EAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QAEpE,MAAM,UAAU,GAAG,MAAM,IAAA,gCAAgB,EACvC,QAAQ,EACR,SAAS,EACT,WAAW,EACX,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,OAAO,CACf,CAAC;QAEF,MAAM,IAAA,4BAAgB,EACpB,QAAQ,EACR,SAAS,EACT,WAAW,EACX,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,OAAO,EACd,UAAU,EACV,MAAM,CAAC,aAAa,CAAC,cAAc,CACpC,CAAC;QAEF,2BAAU,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,IAAI,EAAyB,CAAC,CAAC;IAC/D,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,2BAAU,EAAE,WAAW,CAAC;YACtB,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,GAAG,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC;SACZ,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC,CAAC,EAAE,CAAC"}
+{"version":3,"file":"fileWorker.js","sourceRoot":"","sources":["../src/fileWorker.ts"],"names":[],"mappings":";;AAAA;;;;;;;GAOG;AACH,mDAAwD;AACxD,yCAA+C;AAC/C,qDAAqD;AACrD,mDAAmD;AACnD,2CAA+C;AAE/C,+CAAiE;AAajE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,2BAAyB,CAAC;AAEpE,CAAC,KAAK,IAAI,EAAE;IACV,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,IAAA,4BAAiB,EAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAE3D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,2BAAU,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,IAAI,EAAyB,CAAC,CAAC;YAC7D,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,IAAA,kCAAiB,EAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QAEpE,MAAM,UAAU,GAAG,MAAM,IAAA,gCAAgB,EACvC,QAAQ,EACR,SAAS,EACT,WAAW,EACX,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,OAAO,CACf,CAAC;QAEF,MAAM,SAAS,GAAG,MAAM,IAAA,4BAAgB,EACtC,QAAQ,EACR,SAAS,EACT,WAAW,EACX,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,OAAO,EACd,UAAU,EACV,MAAM,CAAC,aAAa,CAAC,cAAc,CACpC,CAAC;QAEF,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,IAAA,6BAAe,EAC3B,QAAQ,EACR,WAAW,EACX,SAAS,CAAC,KAAK,EACf,SAAS,CAAC,MAAM,EAChB,SAAS,CAAC,OAAO,CAClB,CAAC;YACF,IAAA,6BAAe,EAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QACtC,CAAC;QAED,2BAAU,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,IAAI,EAAyB,CAAC,CAAC;IAC/D,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,2BAAU,EAAE,WAAW,CAAC;YACtB,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,GAAG,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC;SACZ,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC,CAAC,EAAE,CAAC"}

package/dist/frameworkAdapter.d.ts

@@ -13,6 +13,10 @@ export interface TestFrameworkAdapter {
     mockFn(): string;
     /** `jest.clearAllMocks()` / `vi.clearAllMocks()` */
     clearAllMocks(): string;
+    /** `jest.resetAllMocks()` / `vi.resetAllMocks()` — also resets mock implementations */
+    resetAllMocks(): string;
+    /** `jest.restoreAllMocks()` / `vi.restoreAllMocks()` — restores spyOn mocks */
+    restoreAllMocks(): string;
     /**
      * Cast expression prefix for setting up a mock return value on a named import.
      * Jest: `(name as jest.Mock)`
@@ -32,6 +36,8 @@ export declare class JestAdapter implements TestFrameworkAdapter {
     mockModuleCheck(importPath: string): string;
     mockFn(): string;
     clearAllMocks(): string;
+    resetAllMocks(): string;
+    restoreAllMocks(): string;
     mockCast(name: string): string;
     mockResolvedValue(name: string, val: string): string;
     mockReturnValue(name: string, val: string): string;
@@ -43,6 +49,8 @@ export declare class VitestAdapter implements TestFrameworkAdapter {
     mockModuleCheck(importPath: string): string;
     mockFn(): string;
     clearAllMocks(): string;
+    resetAllMocks(): string;
+    restoreAllMocks(): string;
     mockCast(name: string): string;
     mockResolvedValue(name: string, val: string): string;
     mockReturnValue(name: string, val: string): string;

package/dist/frameworkAdapter.js

@@ -24,6 +24,12 @@ class JestAdapter {
     clearAllMocks() {
         return "jest.clearAllMocks();";
     }
+    resetAllMocks() {
+        return "jest.resetAllMocks();";
+    }
+    restoreAllMocks() {
+        return "jest.restoreAllMocks();";
+    }
     mockCast(name) {
         return `(${name} as jest.Mock)`;
     }
@@ -41,7 +47,7 @@ exports.JestAdapter = JestAdapter;
 // ── Vitest adapter ────────────────────────────────────────────────────────────
 class VitestAdapter {
     frameworkImport() {
-        return "import { describe, test, expect, vi, beforeEach } from 'vitest';";
+        return "import { describe, test, expect, vi, beforeEach, afterEach, afterAll } from 'vitest';";
     }
     mockModule(importPath, importedNames) {
         const fns = importedNames.map((n) => `  ${n}: vi.fn(),`).join("\n");
@@ -56,6 +62,12 @@ class VitestAdapter {
     clearAllMocks() {
         return "vi.clearAllMocks();";
     }
+    resetAllMocks() {
+        return "vi.resetAllMocks();";
+    }
+    restoreAllMocks() {
+        return "vi.restoreAllMocks();";
+    }
     mockCast(name) {
         return `vi.mocked(${name})`;
     }

package/dist/frameworkAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"frameworkAdapter.js","sourceRoot":"","sources":["../src/frameworkAdapter.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAuHH,sCAEC;AAtFD,iFAAiF;AAEjF,MAAa,WAAW;IACpB,eAAe;QACX,OAAO,EAAE,CAAC;IACd,CAAC;IAED,UAAU,CAAC,UAAkB,EAAE,aAAuB;QAClD,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,OAAO,cAAc,UAAU,gBAAgB,GAAG,QAAQ,CAAC;IAC/D,CAAC;IAED,eAAe,CAAC,UAAkB;QAC9B,OAAO,cAAc,UAAU,GAAG,CAAC;IACvC,CAAC;IAED,MAAM;QACF,OAAO,WAAW,CAAC;IACvB,CAAC;IAED,aAAa;QACT,OAAO,uBAAuB,CAAC;IACnC,CAAC;IAED,QAAQ,CAAC,IAAY;QACjB,OAAO,IAAI,IAAI,gBAAgB,CAAC;IACpC,CAAC;IAED,iBAAiB,CAAC,IAAY,EAAE,GAAW;QACvC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAC/D,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,GAAW;QACrC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAC7D,CAAC;IAED,iBAAiB,CAAC,GAAW;QACzB,OAAO,6BAA6B,GAAG,GAAG,CAAC;IAC/C,CAAC;CACJ;AArCD,kCAqCC;AAED,iFAAiF;AAEjF,MAAa,aAAa;IACtB,eAAe;QACX,OAAO,kEAAkE,CAAC;IAC9E,CAAC;IAED,UAAU,CAAC,UAAkB,EAAE,aAAuB;QAClD,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpE,OAAO,YAAY,UAAU,gBAAgB,GAAG,QAAQ,CAAC;IAC7D,CAAC;IAED,eAAe,CAAC,UAAkB;QAC9B,OAAO,YAAY,UAAU,GAAG,CAAC;IACrC,CAAC;IAED,MAAM;QACF,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,aAAa;QACT,OAAO,qBAAqB,CAAC;IACjC,CAAC;IAED,QAAQ,CAAC,IAAY;QACjB,OAAO,aAAa,IAAI,GAAG,CAAC;IAChC,CAAC;IAED,iBAAiB,CAAC,IAAY,EAAE,GAAW;QACvC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAC/D,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,GAAW;QACrC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAC7D,CAAC;IAED,iBAAiB,CAAC,GAAW;QACzB,OAAO,2BAA2B,GAAG,GAAG,CAAC;IAC7C,CAAC;CACJ;AArCD,sCAqCC;AAED,iFAAiF;AAEjF,SAAgB,aAAa,CAAC,YAA+B,MAAM;IAC/D,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"frameworkAdapter.js","sourceRoot":"","sources":["../src/frameworkAdapter.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AA6IH,sCAEC;AAtGD,iFAAiF;AAEjF,MAAa,WAAW;IACpB,eAAe;QACX,OAAO,EAAE,CAAC;IACd,CAAC;IAED,UAAU,CAAC,UAAkB,EAAE,aAAuB;QAClD,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,OAAO,cAAc,UAAU,gBAAgB,GAAG,QAAQ,CAAC;IAC/D,CAAC;IAED,eAAe,CAAC,UAAkB;QAC9B,OAAO,cAAc,UAAU,GAAG,CAAC;IACvC,CAAC;IAED,MAAM;QACF,OAAO,WAAW,CAAC;IACvB,CAAC;IAED,aAAa;QACT,OAAO,uBAAuB,CAAC;IACnC,CAAC;IAED,aAAa;QACT,OAAO,uBAAuB,CAAC;IACnC,CAAC;IAED,eAAe;QACX,OAAO,yBAAyB,CAAC;IACrC,CAAC;IAED,QAAQ,CAAC,IAAY;QACjB,OAAO,IAAI,IAAI,gBAAgB,CAAC;IACpC,CAAC;IAED,iBAAiB,CAAC,IAAY,EAAE,GAAW;QACvC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAC/D,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,GAAW;QACrC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAC7D,CAAC;IAED,iBAAiB,CAAC,GAAW;QACzB,OAAO,6BAA6B,GAAG,GAAG,CAAC;IAC/C,CAAC;CACJ;AA7CD,kCA6CC;AAED,iFAAiF;AAEjF,MAAa,aAAa;IACtB,eAAe;QACX,OAAO,uFAAuF,CAAC;IACnG,CAAC;IAED,UAAU,CAAC,UAAkB,EAAE,aAAuB;QAClD,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpE,OAAO,YAAY,UAAU,gBAAgB,GAAG,QAAQ,CAAC;IAC7D,CAAC;IAED,eAAe,CAAC,UAAkB;QAC9B,OAAO,YAAY,UAAU,GAAG,CAAC;IACrC,CAAC;IAED,MAAM;QACF,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,aAAa;QACT,OAAO,qBAAqB,CAAC;IACjC,CAAC;IAED,aAAa;QACT,OAAO,qBAAqB,CAAC;IACjC,CAAC;IAED,eAAe;QACX,OAAO,uBAAuB,CAAC;IACnC,CAAC;IAED,QAAQ,CAAC,IAAY;QACjB,OAAO,aAAa,IAAI,GAAG,CAAC;IAChC,CAAC;IAED,iBAAiB,CAAC,IAAY,EAAE,GAAW;QACvC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAC/D,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,GAAW;QACrC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAC7D,CAAC;IAED,iBAAiB,CAAC,GAAW;QACzB,OAAO,2BAA2B,GAAG,GAAG,CAAC;IAC7C,CAAC;CACJ;AA7CD,sCA6CC;AAED,iFAAiF;AAEjF,SAAgB,aAAa,CAAC,YAA+B,MAAM;IAC/D,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC;AAC5E,CAAC"}

package/dist/generator.d.ts

@@ -1,5 +1,28 @@
 import { TestScenario } from "./scenarioEngine";
 import { MockFileResult } from "./mockGenerator";
+/**
+ * Marker placed as the very first line of every generated test file.
+ * Its presence lets cotester know the file was scaffolded (not hand-written),
+ * but function-level merging works regardless of whether the marker is present.
+ */
+export declare const TESTGEN_MARKER = "// @cotester-generated";
+/**
+ * Format version written into the second line of every generated test file.
+ * Used by `cotester migrate` to detect files produced by older versions and
+ * upgrade them in-place.  Increment this when the generated format changes.
+ */
+export declare const CURRENT_FILE_VERSION = 2;
+export declare const VERSION_MARKER = "// @cotester-version: 2";
+/** Returned by generateTestFile — carries the test file path and audit data. */
+export interface GenerateResult {
+    testFilePath: string;
+    /** Function names for which a new describe block was written */
+    added: string[];
+    /** Function names whose signature changed (describe existed, warning injected) */
+    merged: string[];
+    /** Function names already covered and left untouched */
+    skipped: string[];
+}
 /**
  * Generate (or merge into) a test file for the given source file.
  *
@@ -13,4 +36,4 @@ import { MockFileResult } from "./mockGenerator";
  * Individual functions/methods that already have a describe block are never
  * touched, preserving any hand-written assertions inside them.
  */
-export declare function generateTestFile(srcFilePath: string, scenarios: TestScenario[], projectRoot: string, srcDir: string, testDir: string, mockResult: MockFileResult | null, tableThreshold?: number, dryRun?: boolean, framework?: "jest" | "vitest", snapshotForComplexTypes?: boolean): Promise<string | null>;
+export declare function generateTestFile(srcFilePath: string, scenarios: TestScenario[], projectRoot: string, srcDir: string, testDir: string, mockResult: MockFileResult | null, tableThreshold?: number, dryRun?: boolean, framework?: "jest" | "vitest", snapshotForComplexTypes?: boolean): Promise<GenerateResult | null>;

package/dist/generator.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION_MARKER = exports.CURRENT_FILE_VERSION = exports.TESTGEN_MARKER = void 0;
 exports.generateTestFile = generateTestFile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -45,7 +46,14 @@ const frameworkAdapter_1 = require("./frameworkAdapter");
  * Its presence lets cotester know the file was scaffolded (not hand-written),
  * but function-level merging works regardless of whether the marker is present.
  */
-const TESTGEN_MARKER = "// @cotester-generated";
+exports.TESTGEN_MARKER = "// @cotester-generated";
+/**
+ * Format version written into the second line of every generated test file.
+ * Used by `cotester migrate` to detect files produced by older versions and
+ * upgrade them in-place.  Increment this when the generated format changes.
+ */
+exports.CURRENT_FILE_VERSION = 2;
+exports.VERSION_MARKER = `// @cotester-version: ${exports.CURRENT_FILE_VERSION}`;
 /**
  * Generate (or merge into) a test file for the given source file.
  *
@@ -75,7 +83,8 @@ async function generateTestFile(srcFilePath, scenarios, projectRoot, srcDir, tes
         process.stdout.write(`// [dry-run] Test file: ${relTest}\n`);
         process.stdout.write(`${"─".repeat(60)}\n`);
         process.stdout.write(formatted);
-        return testFilePath;
+        const allNames = scenarios.map((s) => s.functionName);
+        return { testFilePath, added: allNames, merged: [], skipped: [] };
     }
     (0, utils_1.ensureDir)(path.dirname(testFilePath));
     // ── Brand-new file → generate everything ─────────────────────────────
@@ -84,7 +93,8 @@ async function generateTestFile(srcFilePath, scenarios, projectRoot, srcDir, tes
         const formatted = await (0, formatter_1.formatCode)(code, projectRoot);
         fs.writeFileSync(testFilePath, formatted, "utf-8");
         (0, utils_1.log)(`Test file → ${path.relative(projectRoot, testFilePath)}`, "success");
-        return testFilePath;
+        const allNames = scenarios.map((s) => s.functionName);
+        return { testFilePath, added: allNames, merged: [], skipped: [] };
     }
     // ── File exists → function-level merge ───────────────────────────────
     return mergeIntoExistingTestFile(scenarios, srcFilePath, testFilePath, mockResult, projectRoot, srcDir, tableThreshold, adapter, snapshotForComplexTypes);
@@ -105,6 +115,7 @@ async function mergeIntoExistingTestFile(scenarios, srcFilePath, testFilePath, m
     const existingDescribes = detectExistingDescribes(content);
     // ── Feature 6: signature-change detection for already-covered describes ──
     const existingSigs = parseExistingSignatures(content);
+    const sigChangedNames = new Set();
     for (const s of scenarios) {
         const key = s.functionName;
         if (!existingDescribes.has(key))
@@ -120,6 +131,7 @@ async function mergeIntoExistingTestFile(scenarios, srcFilePath, testFilePath, m
             (0, utils_1.log)(`  Signature changed for ${key} — injecting update warning.`, "warn");
             content = updateSignatureComment(content, key, newSig);
             content = injectSignatureWarning(content, key, oldSig, newSig);
+            sigChangedNames.add(key);
         }
     }
     // ── Classify scenarios ───────────────────────────────────────────────
@@ -161,9 +173,16 @@ async function mergeIntoExistingTestFile(scenarios, srcFilePath, testFilePath, m
     for (const fn of missingStandalone) {
         toAppend.push(buildFunctionDescribe(fn, mockResult, tableThreshold, adapter, snapshotForComplexTypes));
     }
+    // ── Build audit lists ────────────────────────────────────────────────
+    const addedNames = newScenarios.map((s) => s.functionName);
+    const mergedNames = Array.from(sigChangedNames);
+    const skippedNames = scenarios
+        .filter((s) => existingDescribes.has(s.functionName) &&
+        !sigChangedNames.has(s.functionName))
+        .map((s) => s.functionName);
     if (toAppend.length === 0 && newScenarios.length === 0) {
         (0, utils_1.log)(`  ${path.relative(projectRoot, testFilePath)} — all functions already covered.`, "info");
-        return testFilePath;
+        return { testFilePath, added: [], merged: mergedNames, skipped: skippedNames };
     }
     // ── Append standalone / new-class blocks ─────────────────────────────
     if (toAppend.length > 0) {
@@ -173,9 +192,8 @@ async function mergeIntoExistingTestFile(scenarios, srcFilePath, testFilePath, m
     content = addMissingMocks(content, newScenarios, srcFilePath, testFilePath, adapter);
     const formatted = await (0, formatter_1.formatCode)(content, projectRoot);
     fs.writeFileSync(testFilePath, formatted, "utf-8");
-    const addedCount = newScenarios.length;
-    (0, utils_1.log)(`Test file updated → ${path.relative(projectRoot, testFilePath)} (+${addedCount} function(s))`, "success");
-    return testFilePath;
+    (0, utils_1.log)(`Test file updated → ${path.relative(projectRoot, testFilePath)} (+${addedNames.length} function(s))`, "success");
+    return { testFilePath, added: addedNames, merged: mergedNames, skipped: skippedNames };
 }
 // ─── Merge helpers ────────────────────────────────────────────────────────────
 /**
@@ -305,13 +323,42 @@ function addMissingMocks(content, newScenarios, srcFilePath, testFilePath, adapt
     }
     if (mockLines.length === 0 && importLines.length === 0)
         return content;
-    const injection = [...mockLines, ...importLines].join("\n") + "\n\n";
-    // Prepend before the first import statement (or before the first describe as fallback)
-    const firstImportIdx = content.indexOf("import ");
-    if (firstImportIdx !== -1) {
-        return content.substring(0, firstImportIdx) + injection + content.substring(firstImportIdx);
+    // ── Step 1: insert jest.mock() calls before ALL imports ─────────────
+    // Jest's babel-jest transform hoists jest.mock() above imports, but keeping
+    // them before imports is cleaner and avoids confusion.
+    let result = content;
+    if (mockLines.length > 0) {
+        const mockBlock = mockLines.join("\n") + "\n\n";
+        const firstImportIdx = result.indexOf("import ");
+        if (firstImportIdx !== -1) {
+            result = result.substring(0, firstImportIdx) + mockBlock + result.substring(firstImportIdx);
+        }
+        else {
+            result = mockBlock + result;
+        }
+    }
+    // ── Step 2: insert named imports AFTER the last existing import ─────
+    // This keeps framework imports (vitest/jest) at the top and source
+    // imports grouped together.
+    if (importLines.length > 0) {
+        const importBlock = importLines.join("\n");
+        // Find the last "import " line to append new imports after it
+        const lines = result.split("\n");
+        let lastImportLineIdx = -1;
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].trimStart().startsWith("import ")) {
+                lastImportLineIdx = i;
+            }
+        }
+        if (lastImportLineIdx !== -1) {
+            lines.splice(lastImportLineIdx + 1, 0, importBlock);
+            result = lines.join("\n");
+        }
+        else {
+            result = result + "\n" + importBlock;
+        }
     }
-    return injection + content;
+    return result;
 }
 function escapeForRegex(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -321,7 +368,8 @@ function buildTestSource(scenarios, srcFilePath, testFilePath, mockResult, proje
     const lines = [];
     // Marker — presence of this line tells cotester the file is auto-generated
     // and safe to regenerate. Remove it to protect hand-written edits.
-    lines.push(TESTGEN_MARKER);
+    lines.push(exports.TESTGEN_MARKER);
+    lines.push(exports.VERSION_MARKER);
     lines.push("");
     // ── Framework import (Vitest only; empty for Jest) ───────────────
     const fwImport = adapter.frameworkImport();
@@ -398,7 +446,11 @@ function buildTestSource(scenarios, srcFilePath, testFilePath, mockResult, proje
 function buildClassDescribe(className, methods, mockResult, tableThreshold = 0, adapter = (0, frameworkAdapter_1.createAdapter)("jest"), snapshotForComplexTypes = false) {
     const lines = [];
     lines.push(`describe(${JSON.stringify(className)}, () => {`);
-    lines.push(`  let instance: ${className};`);
+    // Determine if the class has any instance methods (non-static) before declaring `instance`
+    const hasInstanceMethods = methods.some((m) => !m.isStatic);
+    if (hasInstanceMethods) {
+        lines.push(`  let instance: ${className};`);
+    }
     // Generate mock objects for constructor dependencies
     const ctorParams = methods[0]?.constructorParams ?? [];
     const ormUsage = methods[0]?.ormUsage;
@@ -425,10 +477,27 @@ function buildClassDescribe(className, methods, mockResult, tableThreshold = 0,
                 mockDeclarations.push(`  const ${mockName} = { find: ${fn}, findById: ${fn}, save: ${fn}, create: ${fn}, update: ${fn}, delete: ${fn} } as any;`);
             }
             else if (typeLower.includes("service")) {
-                mockDeclarations.push(`  const ${mockName} = { } as any; // TODO: mock ${param.type} methods`);
+                const fn = adapter.mockFn();
+                mockDeclarations.push(`  const ${mockName} = { findAll: ${fn}, findOne: ${fn}, findById: ${fn}, create: ${fn}, update: ${fn}, delete: ${fn} } as any;`);
+                mockDeclarations.push(`  // TODO: add or remove ${param.type} mock methods to match the actual interface`);
+            }
+            else if (typeLower.includes("logger") || typeLower.includes("log")) {
+                const fn = adapter.mockFn();
+                mockDeclarations.push(`  const ${mockName} = { log: ${fn}, warn: ${fn}, error: ${fn}, debug: ${fn}, verbose: ${fn} } as any;`);
+            }
+            else if (typeLower.includes("cache") || typeLower.includes("redis")) {
+                const fn = adapter.mockFn();
+                mockDeclarations.push(`  const ${mockName} = { get: ${fn}, set: ${fn}, del: ${fn}, exists: ${fn} } as any;`);
+            }
+            else if (typeLower.includes("queue") || typeLower.includes("producer") || typeLower.includes("publisher")) {
+                const fn = adapter.mockFn();
+                mockDeclarations.push(`  const ${mockName} = { send: ${fn}, emit: ${fn}, publish: ${fn}, add: ${fn} } as any;`);
             }
             else {
+                const fn = adapter.mockFn();
                 mockDeclarations.push(`  const ${mockName} = { } as any; // TODO: add mock methods for ${param.type}`);
+                // Suppress the unused variable warning when no methods are known
+                mockDeclarations.push(`  void ${mockName}; // remove this line once you add method stubs above`);
             }
         }
     }
@@ -440,17 +509,29 @@ function buildClassDescribe(className, methods, mockResult, tableThreshold = 0,
     }
     lines.push("");
     lines.push("  beforeEach(() => {");
-    lines.push(`    ${adapter.clearAllMocks()}`);
-    if (ctorParams.length > 0) {
-        const args = ctorParams
-            .map((p) => `mock${capitalize(p.name)}`)
-            .join(", ");
-        lines.push(`    instance = new ${className}(${args});`);
-    }
-    else {
-        lines.push(`    instance = new ${className}();`);
+    lines.push(`    ${adapter.resetAllMocks()}`);
+    if (hasInstanceMethods) {
+        if (ctorParams.length > 0) {
+            const args = ctorParams
+                .map((p) => `mock${capitalize(p.name)}`)
+                .join(", ");
+            lines.push(`    instance = new ${className}(${args});`);
+        }
+        else {
+            lines.push(`    instance = new ${className}();`);
+        }
     }
     lines.push("  });");
+    lines.push("");
+    lines.push("  afterEach(() => {");
+    lines.push(`    ${adapter.restoreAllMocks()}`);
+    lines.push("  });");
+    if (ctorParams.length > 0) {
+        lines.push("");
+        lines.push("  afterAll(() => {");
+        lines.push("    // TODO: release shared resources (DB connections, file handles, timers)");
+        lines.push("  });");
+    }
     // ── FileType-specific setup ──────────────────────────────────────
     const fileType = methods[0]?.fileType ?? "unknown";
     if (fileType === "controller") {
@@ -476,10 +557,23 @@ function buildClassDescribe(className, methods, mockResult, tableThreshold = 0,
         lines.push(`  const mockNext = ${adapter.mockFn()};`);
     }
     lines.push("");
-    for (const method of methods) {
+    // Instance methods
+    const instanceMethods = methods.filter((m) => !m.isStatic);
+    for (const method of instanceMethods) {
         lines.push(indentBlock(buildMethodDescribe(method, mockResult, tableThreshold, adapter, snapshotForComplexTypes), 1));
         lines.push("");
     }
+    // Static methods — grouped in a nested describe block, called via ClassName.method()
+    const staticMethods = methods.filter((m) => m.isStatic);
+    if (staticMethods.length > 0) {
+        lines.push(`  describe('static methods', () => {`);
+        for (const method of staticMethods) {
+            lines.push(indentBlock(buildMethodDescribe(method, mockResult, tableThreshold, adapter, snapshotForComplexTypes), 2));
+            lines.push("");
+        }
+        lines.push(`  });`);
+        lines.push("");
+    }
     lines.push("});");
     return lines.join("\n");
 }
@@ -488,10 +582,14 @@ function buildFunctionDescribe(fn, mockResult, tableThreshold = 0, adapter = (0,
     const lines = [];
     lines.push(`// @testgen-sig:${buildSignatureFingerprint(fn)}`);
     lines.push(`describe(${JSON.stringify(fn.functionName)}, () => {`);
-    // Add beforeEach with clearAllMocks if this function has dependencies
+    // Add beforeEach/afterEach if this function has dependencies
     if (fn.dependencies.length > 0) {
         lines.push("  beforeEach(() => {");
-        lines.push(`    ${adapter.clearAllMocks()}`);
+        lines.push(`    ${adapter.resetAllMocks()}`);
+        lines.push("  });");
+        lines.push("");
+        lines.push("  afterEach(() => {");
+        lines.push(`    ${adapter.restoreAllMocks()}`);
         lines.push("  });");
         lines.push("");
     }
@@ -560,7 +658,10 @@ function buildTableBlock(scenario, tableCases, snapshotForComplexTypes = false)
     const isMethod = !!scenario.className;
     const fnName = scenario.functionName;
     const paramNames = scenario.parameters.map((p) => p.name);
-    lines.push(`test.each([`);
+    // Build TypeScript generic annotation: test.each<[string, ParamType1, ParamType2]>
+    const paramTypes = scenario.parameters.map((p) => p.type || "unknown");
+    const genericAnnotation = `<[string, ${paramTypes.join(", ")}]>`;
+    lines.push(`test.each${genericAnnotation}([`);
     for (const c of tableCases) {
         const args = c.argLiterals.join(", ");
         lines.push(`  [${JSON.stringify(c.label)}, ${args}],`);
@@ -568,7 +669,10 @@ function buildTableBlock(scenario, tableCases, snapshotForComplexTypes = false)
     lines.push(`])('%s', ${isAsync ? "async " : ""}(_label, ${paramNames.join(", ")}) => {`);
     // Act
     lines.push(`  // Act`);
-    const caller = isMethod ? `instance.${fnName}` : fnName;
+    const isStatic = !!scenario.isStatic;
+    const caller = isStatic
+        ? `${scenario.className}.${fnName}`
+        : isMethod ? `instance.${fnName}` : fnName;
     if (isAsync) {
         lines.push(`  const result = await ${caller}(${paramNames.join(", ")});`);
     }
@@ -602,6 +706,7 @@ function buildStandardBlock(scenario, testCase, mockConstName, adapter = (0, fra
     const fnName = scenario.functionName;
     const isAsync = scenario.isAsync;
     const isMethod = !!scenario.className;
+    const isStatic = !!scenario.isStatic;
     const isDependencyTest = testCase.label === "verifies dependency interactions";
     lines.push(`test(${JSON.stringify(testCase.label)}, ${isAsync ? "async " : ""}() => {`);
     // ── Arrange ──────────────────────────────────────────────────────
@@ -655,10 +760,13 @@ function buildStandardBlock(scenario, testCase, mockConstName, adapter = (0, fra
     // ── Act ──────────────────────────────────────────────────────────
     lines.push("  // Act");
     const argsStr = testCase.paramNames.join(", ");
-    const caller = isMethod ? `instance.${fnName}` : fnName;
+    const caller = isStatic
+        ? `${scenario.className}.${fnName}`
+        : isMethod ? `instance.${fnName}` : fnName;
     const callExpr = `${caller}(${argsStr})`;
     if (isAsync) {
         lines.push(`  const result = await ${callExpr};`);
+        lines.push(`  // TIP: alternatively use: await expect(${callExpr}).resolves.toBeDefined()`);
     }
     else {
         lines.push(`  const result = ${callExpr};`);
@@ -701,6 +809,7 @@ function buildThrowsBlock(scenario, testCase, mockConstName) {
     const lines = [];
     const fnName = scenario.functionName;
     const isMethod = !!scenario.className;
+    const isStatic = !!scenario.isStatic;
     lines.push(`test(${JSON.stringify(testCase.label)}, () => {`);
     // ── Arrange ──────────────────────────────────────────────────────
     const caseKey = camelCase(testCase.label);
@@ -724,8 +833,11 @@ function buildThrowsBlock(scenario, testCase, mockConstName) {
     // ── Act & Assert ────────────────────────────────────────────────
     lines.push("  // Act & Assert");
     const argsStr = testCase.paramNames.join(", ");
-    const caller = isMethod ? `instance.${fnName}` : fnName;
-    lines.push(`  expect(() => ${caller}(${argsStr})).toThrow();`);
+    const caller = isStatic
+        ? `${scenario.className}.${fnName}`
+        : isMethod ? `instance.${fnName}` : fnName;
+    lines.push(`  expect(() => ${caller}(${argsStr})).toThrow(Error);`);
+    lines.push(`  // TODO: narrow to a specific error type, e.g. .toThrow(ValidationError) or .toThrow('message')`);
     lines.push("});");
     return lines.join("\n");
 }
@@ -734,6 +846,7 @@ function buildRejectsBlock(scenario, testCase, mockConstName) {
     const lines = [];
     const fnName = scenario.functionName;
     const isMethod = !!scenario.className;
+    const isStatic = !!scenario.isStatic;
     lines.push(`test(${JSON.stringify(testCase.label)}, async () => {`);
     // ── Arrange ──────────────────────────────────────────────────────
     const caseKey = camelCase(testCase.label);
@@ -757,8 +870,11 @@ function buildRejectsBlock(scenario, testCase, mockConstName) {
     // ── Act & Assert ────────────────────────────────────────────────
     lines.push("  // Act & Assert");
     const argsStr = testCase.paramNames.join(", ");
-    const caller = isMethod ? `instance.${fnName}` : fnName;
+    const caller = isStatic
+        ? `${scenario.className}.${fnName}`
+        : isMethod ? `instance.${fnName}` : fnName;
     lines.push(`  await expect(${caller}(${argsStr})).rejects.toThrow();`);
+    lines.push(`  // TODO: narrow rejection, e.g. .rejects.toThrow(SpecificError) or .rejects.toThrow('message')`);
     lines.push("});");
     return lines.join("\n");
 }
@@ -825,6 +941,7 @@ function buildExpectStubs(returnType, scenarioLabel, snapshotForComplexTypes = f
             stubs.push("// expect(result).toBe(0);");
         if (scenarioLabel.includes("boundary"))
             stubs.push("expect(Number.isFinite(result)).toBe(true);");
+        stubs.push("// TODO: add domain assertion — e.g. expect(result).toBe(expectedValue)");
     }
     else if (unwrapped === "string") {
         stubs.push("expect(typeof result).toBe('string');");
@@ -832,6 +949,7 @@ function buildExpectStubs(returnType, scenarioLabel, snapshotForComplexTypes = f
             stubs.push("// expect(result).toBe('');");
         if (scenarioLabel.includes("valid"))
             stubs.push("expect(result.length).toBeGreaterThan(0);");
+        stubs.push("// TODO: add domain assertion — e.g. expect(result).toEqual(expectedString)");
     }
     else if (unwrapped === "boolean") {
         stubs.push("expect(typeof result).toBe('boolean');");
@@ -839,21 +957,28 @@ function buildExpectStubs(returnType, scenarioLabel, snapshotForComplexTypes = f
             stubs.push("// expect(result).toBe(true);");
         if (scenarioLabel.includes("falsy"))
             stubs.push("// expect(result).toBe(false);");
+        stubs.push("// TODO: add domain assertion — e.g. expect(result).toBe(true)");
+    }
+    else if (unwrapped === "null") {
+        stubs.length = 0;
+        stubs.push("expect(result).toBeNull();");
     }
-    else if (unwrapped === "void") {
+    else if (unwrapped === "void" || unwrapped === "undefined") {
         stubs.length = 0;
         stubs.push("expect(result).toBeUndefined();");
     }
-    else if (unwrapped.endsWith("[]")) {
+    else if (unwrapped.endsWith("[]") || unwrapped.startsWith("array<")) {
         stubs.push("expect(Array.isArray(result)).toBe(true);");
         if (scenarioLabel.includes("empty"))
             stubs.push("// expect(result).toHaveLength(0);");
+        stubs.push("// TODO: add domain assertion — e.g. expect(result).toHaveLength(n) or toContainEqual(item)");
     }
     else {
         stubs.push("expect(result).not.toBeNull();");
         if (snapshotForComplexTypes && isComplexReturnType(unwrapped)) {
             stubs.push("expect(result).toMatchSnapshot(); // Update snapshot after first run");
         }
+        stubs.push("// TODO: add domain assertion — e.g. expect(result).toEqual(expected) or toHaveProperty('key', value)");
     }
     return stubs;
 }