From a8fed0c26dd47837e655f4605fecee460e4f8f63 Mon Sep 17 00:00:00 2001
From: Ihor Kosheliev <137728460+i-kosheliev@users.noreply.github.com>
Date: Tue, 14 Apr 2026 01:43:11 +0300
Subject: [PATCH 1/4] =?UTF-8?q?feat:=20CLI=20scanner=20=E2=80=94=20static?=
 =?UTF-8?q?=20test=20quality=20analysis=20AB#434?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

npx @iklab/testkit scan ./tests — analyzes test files for:
- Flaky code patterns (setTimeout, fetch, Date.now, Math.random, process.env, fs I/O)
- Missing assertions (test bodies without expect/assert)
- Conditional assertions (expect inside if/else)
- Focused tests (.only) and skipped tests (.skip, x-prefix)
- Duplicate test names across files (Jaccard similarity)
- Flaky descriptions (reuses existing flaky() function)

Architecture: AST-based using acorn + @sveltejs/acorn-typescript.
Two-tier analysis: structure extraction + code body scanning.
Text output with ANSI colors + --json flag for CI.
Exit codes: 0 clean, 1 issues found, 2 fatal error.

24 new tests (scanner.test.ts), 150 total passing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 jest.config.js                                |   8 +
 package-lock.json                             |  17 +-
 package.json                                  |  14 +-
 src/__tests__/fixtures/clean.test.ts          |  16 +
 src/__tests__/fixtures/flaky.test.ts          |  23 ++
 src/__tests__/fixtures/quality-issues.test.ts |  28 ++
 src/__tests__/scanner.test.ts                 | 220 +++++++++++++
 src/cli.ts                                    | 296 ++++++++++++++++++
 src/reporter/json-reporter.ts                 |   9 +
 src/reporter/text-reporter.ts                 | 117 +++++++
 src/scanner/ast-parser.ts                     |  29 ++
 src/scanner/code-analyzer.ts                  | 273 ++++++++++++++++
 src/scanner/file-discovery.ts                 | 103 ++++++
 src/scanner/test-extractor.ts                 | 154 +++++++++
 src/scanner/types.ts                          | 106 +++++++
 tsup.config.ts                                |  32 +-
 16 files changed, 1434 insertions(+), 11 deletions(-)
 create mode 100644 src/__tests__/fixtures/clean.test.ts
 create mode 100644 src/__tests__/fixtures/flaky.test.ts
 create mode 100644 src/__tests__/fixtures/quality-issues.test.ts
 create mode 100644 src/__tests__/scanner.test.ts
 create mode 100644 src/cli.ts
 create mode 100644 src/reporter/json-reporter.ts
 create mode 100644 src/reporter/text-reporter.ts
 create mode 100644 src/scanner/ast-parser.ts
 create mode 100644 src/scanner/code-analyzer.ts
 create mode 100644 src/scanner/file-discovery.ts
 create mode 100644 src/scanner/test-extractor.ts
 create mode 100644 src/scanner/types.ts

diff --git a/jest.config.js b/jest.config.js
index b6d55c7..85aa783 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -4,4 +4,12 @@ module.exports = {
   testEnvironment: "node",
   roots: ["<rootDir>/src"],
   testMatch: ["**/__tests__/**/*.test.ts"],
+  testPathIgnorePatterns: ["/node_modules/", "/__tests__/fixtures/"],
+  transformIgnorePatterns: [
+    "/node_modules/(?!(@sveltejs/acorn-typescript|acorn)/)",
+  ],
+  transform: {
+    "^.+\\.tsx?$": "ts-jest",
+    "node_modules/@sveltejs/acorn-typescript/.+\\.js$": "ts-jest",
+  },
 };
diff --git a/package-lock.json b/package-lock.json
index 74007b8..f7d89ca 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,12 +8,19 @@
       "name": "@iklab/testkit",
       "version": "1.0.0",
       "license": "MIT",
+      "dependencies": {
+        "@sveltejs/acorn-typescript": "^1.0.9",
+        "acorn": "^8.16.0"
+      },
       "devDependencies": {
         "@types/jest": "^29.5.14",
         "jest": "^29.7.0",
         "ts-jest": "^29.2.5",
         "tsup": "^8.4.0",
         "typescript": "^5.7.0"
+      },
+      "engines": {
+        "node": ">=18"
       }
     },
     "node_modules/@babel/code-frame": {
@@ -1700,6 +1707,15 @@
         "@sinonjs/commons": "^3.0.0"
       }
     },
+    "node_modules/@sveltejs/acorn-typescript": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@sveltejs/acorn-typescript/-/acorn-typescript-1.0.9.tgz",
+      "integrity": "sha512-lVJX6qEgs/4DOcRTpo56tmKzVPtoWAaVbL4hfO7t7NVwl9AAXzQR6cihesW1BmNMPl+bK6dreu2sOKBP2Q9CIA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "acorn": "^8.9.0"
+      }
+    },
     "node_modules/@types/babel__core": {
       "version": "7.20.5",
       "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz",
@@ -1838,7 +1854,6 @@
       "version": "8.16.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
-      "dev": true,
       "license": "MIT",
       "bin": {
         "acorn": "bin/acorn"
diff --git a/package.json b/package.json
index 958d533..28c8399 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@iklab/testkit",
   "version": "1.0.0",
-  "description": "Structured test data for developers — boundary values, flakiness prediction, duplicate detection. Zero deps.",
+  "description": "Test quality toolkit — boundary values, flakiness prediction, duplicate detection, static test scanner.",
   "author": "Ihor Kosheliev",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,10 @@
     "test-each",
     "ISTQB",
     "duplicate-detection",
-    "test-automation"
+    "test-automation",
+    "static-analysis",
+    "cli",
+    "scanner"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -37,6 +40,9 @@
       }
     }
   },
+  "bin": {
+    "testkit": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "LICENSE",
@@ -63,5 +69,9 @@
     "ts-jest": "^29.2.5",
     "tsup": "^8.4.0",
     "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "@sveltejs/acorn-typescript": "^1.0.9",
+    "acorn": "^8.16.0"
   }
 }
diff --git a/src/__tests__/fixtures/clean.test.ts b/src/__tests__/fixtures/clean.test.ts
new file mode 100644
index 0000000..774239b
--- /dev/null
+++ b/src/__tests__/fixtures/clean.test.ts
@@ -0,0 +1,16 @@
+// Fixture: clean test file with no issues
+describe("Calculator", () => {
+  it("should add two numbers", () => {
+    expect(1 + 1).toBe(2);
+  });
+
+  it("should subtract two numbers", () => {
+    expect(5 - 3).toBe(2);
+  });
+
+  describe("edge cases", () => {
+    it("should handle zero", () => {
+      expect(0 + 0).toBe(0);
+    });
+  });
+});
diff --git a/src/__tests__/fixtures/flaky.test.ts b/src/__tests__/fixtures/flaky.test.ts
new file mode 100644
index 0000000..4701fc2
--- /dev/null
+++ b/src/__tests__/fixtures/flaky.test.ts
@@ -0,0 +1,23 @@
+// Fixture: test file with flaky code patterns
+describe("API Integration", () => {
+  it("should wait for login redirect", () => {
+    setTimeout(() => {
+      expect(window.location.href).toContain("/dashboard");
+    }, 3000);
+  });
+
+  it("should fetch user data", () => {
+    const response = fetch("/api/users");
+    expect(response).toBeDefined();
+  });
+
+  it("should handle timestamp", () => {
+    const now = Date.now();
+    expect(now).toBeGreaterThan(0);
+  });
+
+  it("should generate random id", () => {
+    const id = Math.random().toString(36);
+    expect(id).toBeTruthy();
+  });
+});
diff --git a/src/__tests__/fixtures/quality-issues.test.ts b/src/__tests__/fixtures/quality-issues.test.ts
new file mode 100644
index 0000000..ab42dea
--- /dev/null
+++ b/src/__tests__/fixtures/quality-issues.test.ts
@@ -0,0 +1,28 @@
+// Fixture: test file with quality issues
+describe("Features", () => {
+  it("should render page", () => {
+    // No assertions — empty test body
+    const element = document.getElementById("app");
+  });
+
+  it.skip("should validate email", () => {
+    expect("a@b.com").toMatch(/@/);
+  });
+
+  it.only("should process order", () => {
+    expect(true).toBe(true);
+  });
+
+  it("should handle error conditionally", () => {
+    const status = 200;
+    if (status === 200) {
+      expect(status).toBe(200);
+    }
+  });
+});
+
+xdescribe("Disabled suite", () => {
+  xit("disabled test", () => {
+    expect(1).toBe(1);
+  });
+});
diff --git a/src/__tests__/scanner.test.ts b/src/__tests__/scanner.test.ts
new file mode 100644
index 0000000..cd29d09
--- /dev/null
+++ b/src/__tests__/scanner.test.ts
@@ -0,0 +1,220 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseFile } from "../scanner/ast-parser";
+import { extractTests } from "../scanner/test-extractor";
+import { analyzeCode } from "../scanner/code-analyzer";
+import { discoverTestFiles, getRelativePath } from "../scanner/file-discovery";
+
+const FIXTURES = join(__dirname, "fixtures");
+
+function readFixture(name: string): string {
+  return readFileSync(join(FIXTURES, name), "utf-8");
+}
+
+function parseFixture(name: string) {
+  const source = readFixture(name);
+  return parseFile(source, name);
+}
+
+// ─── AST Parser ─────────────────────────────────────────────────────
+
+describe("ast-parser", () => {
+  it("parses a TypeScript file successfully", () => {
+    const ast = parseFixture("clean.test.ts");
+    expect(ast).not.toBeNull();
+    expect((ast as any).body.length).toBeGreaterThan(0);
+  });
+
+  it("returns null for invalid syntax", () => {
+    const ast = parseFile("const x: string = {{{invalid", "bad.ts");
+    expect(ast).toBeNull();
+  });
+
+  it("parses TypeScript type annotations", () => {
+    const ast = parseFile('const x: string = "hello"; const y: number = 42;', "types.ts");
+    expect(ast).not.toBeNull();
+  });
+
+  it("parses arrow functions and async/await", () => {
+    const ast = parseFile('const fn = async (): Promise<void> => { await fetch("/api"); };', "async.ts");
+    expect(ast).not.toBeNull();
+  });
+
+  it("parses plain JavaScript files", () => {
+    const ast = parseFile('describe("test", function() { it("works", function() { expect(1).toBe(1); }); });', "plain.js");
+    expect(ast).not.toBeNull();
+  });
+});
+
+// ─── Test Extractor ─────────────────────────────────────────────────
+
+describe("test-extractor", () => {
+  it("extracts describe/it/test blocks from clean fixture", () => {
+    const ast = parseFixture("clean.test.ts")!;
+    const tests = extractTests(ast);
+
+    expect(tests.length).toBeGreaterThanOrEqual(4); // 1 describe + 2 it + 1 nested describe + 1 nested it
+
+    const describes = tests.filter((t) => t.type === "describe");
+    const its = tests.filter((t) => t.type === "it");
+
+    expect(describes.length).toBeGreaterThanOrEqual(1);
+    expect(its.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it("builds correct fullName with ancestors", () => {
+    const ast = parseFixture("clean.test.ts")!;
+    const tests = extractTests(ast);
+
+    const nestedTest = tests.find((t) => t.name === "should handle zero");
+    expect(nestedTest).toBeDefined();
+    expect(nestedTest!.fullName).toBe("Calculator > edge cases > should handle zero");
+    expect(nestedTest!.ancestors).toEqual(["Calculator", "edge cases"]);
+  });
+
+  it("detects skipped tests (.skip and x-prefix)", () => {
+    const ast = parseFixture("quality-issues.test.ts")!;
+    const tests = extractTests(ast);
+
+    const skipped = tests.filter((t) => t.skipped);
+    expect(skipped.length).toBeGreaterThanOrEqual(2); // it.skip + xit + xdescribe
+  });
+
+  it("detects focused tests (.only)", () => {
+    const ast = parseFixture("quality-issues.test.ts")!;
+    const tests = extractTests(ast);
+
+    const focused = tests.filter((t) => t.focused);
+    expect(focused.length).toBeGreaterThanOrEqual(1); // it.only
+    expect(focused[0].name).toContain("process order");
+  });
+
+  it("reports correct line numbers", () => {
+    const ast = parseFixture("clean.test.ts")!;
+    const tests = extractTests(ast);
+
+    // All tests should have line > 0
+    for (const test of tests) {
+      expect(test.line).toBeGreaterThan(0);
+    }
+  });
+
+  it("handles test() alongside it()", () => {
+    const source = 'test("standalone test", () => { expect(true).toBe(true); });';
+    const ast = parseFile(source, "test-fn.ts")!;
+    const tests = extractTests(ast);
+
+    expect(tests).toHaveLength(1);
+    expect(tests[0].type).toBe("test");
+    expect(tests[0].name).toBe("standalone test");
+  });
+});
+
+// ─── Code Analyzer ──────────────────────────────────────────────────
+
+describe("code-analyzer", () => {
+  it("detects setTimeout in test body", () => {
+    const ast = parseFixture("flaky.test.ts")!;
+    const issues = analyzeCode(ast);
+
+    const timeoutIssue = issues.find((i) => i.message.includes("setTimeout"));
+    expect(timeoutIssue).toBeDefined();
+    expect(timeoutIssue!.type).toBe("flaky-code");
+  });
+
+  it("detects fetch() in test body", () => {
+    const ast = parseFixture("flaky.test.ts")!;
+    const issues = analyzeCode(ast);
+
+    const fetchIssue = issues.find((i) => i.message.includes("HTTP call"));
+    expect(fetchIssue).toBeDefined();
+  });
+
+  it("detects Date.now() in test body", () => {
+    const ast = parseFixture("flaky.test.ts")!;
+    const issues = analyzeCode(ast);
+
+    const dateIssue = issues.find((i) => i.message.includes("Date.now"));
+    expect(dateIssue).toBeDefined();
+  });
+
+  it("detects Math.random() in test body", () => {
+    const ast = parseFixture("flaky.test.ts")!;
+    const issues = analyzeCode(ast);
+
+    const randomIssue = issues.find((i) => i.message.includes("Math.random"));
+    expect(randomIssue).toBeDefined();
+  });
+
+  it("detects missing assertions (no expect)", () => {
+    const ast = parseFixture("quality-issues.test.ts")!;
+    const issues = analyzeCode(ast);
+
+    const noAssert = issues.find((i) => i.type === "no-assertion");
+    expect(noAssert).toBeDefined();
+    expect(noAssert!.message).toContain("no expect/assert");
+  });
+
+  it("detects conditional assertions", () => {
+    const ast = parseFixture("quality-issues.test.ts")!;
+    const issues = analyzeCode(ast);
+
+    const conditional = issues.find((i) => i.type === "conditional-assert");
+    expect(conditional).toBeDefined();
+  });
+
+  it("reports no issues for clean test file", () => {
+    const ast = parseFixture("clean.test.ts")!;
+    const issues = analyzeCode(ast);
+
+    expect(issues).toHaveLength(0);
+  });
+
+  it("includes actionable suggestions", () => {
+    const ast = parseFixture("flaky.test.ts")!;
+    const issues = analyzeCode(ast);
+
+    for (const issue of issues) {
+      expect(issue.suggestion).toBeTruthy();
+      expect(issue.suggestion.length).toBeGreaterThan(10);
+    }
+  });
+});
+
+// ─── File Discovery ─────────────────────────────────────────────────
+
+describe("file-discovery", () => {
+  it("discovers test files in fixtures directory", () => {
+    const files = discoverTestFiles(FIXTURES);
+
+    expect(files.length).toBeGreaterThanOrEqual(3);
+    expect(files.every((f) => f.includes(".test."))).toBe(true);
+  });
+
+  it("returns sorted file paths", () => {
+    const files = discoverTestFiles(FIXTURES);
+
+    for (let i = 1; i < files.length; i++) {
+      expect(files[i] >= files[i - 1]).toBe(true);
+    }
+  });
+
+  it("computes relative path correctly", () => {
+    const rel = getRelativePath("/Users/mac/project/src/test.ts", "/Users/mac/project");
+    expect(rel).toBe("src/test.ts");
+  });
+
+  it("returns empty array for non-existent directory", () => {
+    const files = discoverTestFiles("/non/existent/path");
+    expect(files).toEqual([]);
+  });
+
+  it("excludes node_modules", () => {
+    // discoverTestFiles from project root should not include node_modules
+    const root = join(__dirname, "../..");
+    const files = discoverTestFiles(root);
+
+    const inNodeModules = files.filter((f) => f.includes("node_modules"));
+    expect(inNodeModules).toHaveLength(0);
+  });
+});
diff --git a/src/cli.ts b/src/cli.ts
new file mode 100644
index 0000000..18f4bc9
--- /dev/null
+++ b/src/cli.ts
@@ -0,0 +1,296 @@
+/**
+ * @iklab/testkit CLI — Static Test Quality Scanner
+ *
+ * Usage: npx @iklab/testkit scan ./tests [options]
+ *
+ * Scans test files for flakiness patterns, duplicate descriptions,
+ * missing assertions, and other quality issues.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve, isAbsolute } from "node:path";
+import { discoverTestFiles, getRelativePath } from "./scanner/file-discovery";
+import { parseFile } from "./scanner/ast-parser";
+import { extractTests } from "./scanner/test-extractor";
+import { analyzeCode } from "./scanner/code-analyzer";
+import { flaky } from "./flaky";
+import { detectDuplicates } from "./duplicates";
+import { formatTextReport } from "./reporter/text-reporter";
+import { formatJsonReport } from "./reporter/json-reporter";
+import type {
+  ScanOptions,
+  ScanReport,
+  FileResult,
+  FlakyTestResult,
+  DuplicateTestPair,
+  ExtractedTest,
+} from "./scanner/types";
+
+// ─── CLI Entry Point ────────────────────────────────────────────────
+
+function main(): void {
+  const args = process.argv.slice(2);
+
+  // Help
+  if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Version
+  if (args.includes("--version") || args.includes("-v")) {
+    printVersion();
+    process.exit(0);
+  }
+
+  // Parse command
+  const command = args[0];
+  if (command !== "scan") {
+    console.error(`Unknown command: ${command}. Use "scan" to analyze test files.`);
+    process.exit(2);
+  }
+
+  // Parse options
+  const options = parseArgs(args.slice(1));
+
+  // Run scan
+  try {
+    const report = scan(options);
+    const output = options.format === "json"
+      ? formatJsonReport(report)
+      : formatTextReport(report);
+
+    console.log(output);
+
+    // Exit code: 1 if issues found, 0 if clean
+    const hasIssues =
+      report.summary.issuesFound > 0 ||
+      report.summary.duplicatesFound > 0 ||
+      report.summary.flakyTestsFound > 0 ||
+      report.summary.focusedTests > 0;
+
+    process.exit(hasIssues ? 1 : 0);
+  } catch (error: any) {
+    console.error(`Fatal error: ${error.message}`);
+    process.exit(2);
+  }
+}
+
+// ─── Scan Orchestration ─────────────────────────────────────────────
+
+function scan(options: ScanOptions): ScanReport {
+  const rootDir = isAbsolute(options.dir) ? options.dir : resolve(process.cwd(), options.dir);
+
+  // Phase 1: Discover test files
+  const filePaths = discoverTestFiles(rootDir, options.pattern !== "default" ? options.pattern : undefined);
+
+  if (filePaths.length === 0) {
+    return emptyReport();
+  }
+
+  // Phase 2: Parse and analyze each file
+  const files: FileResult[] = [];
+  const allTests: Array<ExtractedTest & { filePath: string }> = [];
+
+  for (const filePath of filePaths) {
+    const result = analyzeFile(filePath, rootDir, options);
+    files.push(result);
+
+    for (const test of result.tests) {
+      allTests.push({ ...test, filePath });
+    }
+  }
+
+  // Phase 3: Flaky description analysis
+  const flakyTests: FlakyTestResult[] = [];
+  for (const test of allTests) {
+    if (test.type === "describe") continue; // Only analyze leaf tests
+
+    const result = flaky(test.fullName);
+    if (result.score >= options.threshold) {
+      flakyTests.push({
+        fullName: test.fullName,
+        filePath: test.filePath,
+        line: test.line,
+        score: result.score,
+        risks: result.risks,
+        suggestions: result.suggestions,
+      });
+    }
+  }
+
+  // Phase 4: Cross-file duplicate detection
+  const duplicates: DuplicateTestPair[] = [];
+  if (!options.noDuplicates) {
+    const leafTests = allTests.filter((t) => t.type !== "describe");
+
+    if (leafTests.length >= 2) {
+      const descriptions = leafTests.map((t) => t.fullName);
+      const dupResult = detectDuplicates(descriptions, { threshold: 0.7 });
+
+      for (const pair of dupResult.pairs) {
+        const testA = leafTests[pair.indexA];
+        const testB = leafTests[pair.indexB];
+        duplicates.push({
+          nameA: testA.fullName,
+          nameB: testB.fullName,
+          fileA: getRelativePath(testA.filePath, rootDir),
+          lineA: testA.line,
+          fileB: getRelativePath(testB.filePath, rootDir),
+          lineB: testB.line,
+          similarity: pair.similarity,
+        });
+      }
+    }
+  }
+
+  // Build summary
+  const totalTests = allTests.filter((t) => t.type !== "describe").length;
+  const totalCodeIssues = files.reduce((sum, f) => sum + f.codeIssues.length, 0);
+  const skippedTests = allTests.filter((t) => t.skipped && t.type !== "describe").length;
+  const focusedTests = allTests.filter((t) => t.focused).length;
+
+  return {
+    files,
+    flakyTests,
+    duplicates,
+    summary: {
+      filesScanned: files.length,
+      testsFound: totalTests,
+      issuesFound: totalCodeIssues,
+      duplicatesFound: duplicates.length,
+      flakyTestsFound: flakyTests.length,
+      skippedTests,
+      focusedTests,
+    },
+  };
+}
+
+function analyzeFile(filePath: string, rootDir: string, options: ScanOptions): FileResult {
+  const relativePath = getRelativePath(filePath, rootDir);
+
+  let source: string;
+  try {
+    source = readFileSync(filePath, "utf-8");
+  } catch {
+    return {
+      filePath,
+      relativePath,
+      tests: [],
+      codeIssues: [],
+      parseError: "Could not read file",
+    };
+  }
+
+  const ast = parseFile(source, filePath);
+  if (!ast) {
+    return {
+      filePath,
+      relativePath,
+      tests: [],
+      codeIssues: [],
+      parseError: "Could not parse file (syntax error or unsupported syntax)",
+    };
+  }
+
+  const tests = extractTests(ast);
+  const codeIssues = options.noCodeAnalysis ? [] : analyzeCode(ast);
+
+  return {
+    filePath,
+    relativePath,
+    tests,
+    codeIssues,
+  };
+}
+
+// ─── Argument Parsing ───────────────────────────────────────────────
+
+function parseArgs(args: string[]): ScanOptions {
+  const options: ScanOptions = {
+    dir: ".",
+    pattern: "default",
+    format: "text",
+    threshold: 4,
+    noDuplicates: false,
+    noCodeAnalysis: false,
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === "--pattern" && args[i + 1]) {
+      options.pattern = args[++i];
+    } else if (arg === "--json") {
+      options.format = "json";
+    } else if (arg === "--threshold" && args[i + 1]) {
+      const val = parseInt(args[++i], 10);
+      if (val >= 1 && val <= 10) options.threshold = val;
+    } else if (arg === "--no-duplicates") {
+      options.noDuplicates = true;
+    } else if (arg === "--no-code-analysis") {
+      options.noCodeAnalysis = true;
+    } else if (!arg.startsWith("-")) {
+      options.dir = arg;
+    }
+
+    i++;
+  }
+
+  return options;
+}
+
+// ─── Help & Version ─────────────────────────────────────────────────
+
+function printHelp(): void {
+  console.log(`
+@iklab/testkit — Static Test Quality Scanner
+
+Usage:
+  testkit scan <directory> [options]
+
+Options:
+  --pattern <glob>     File pattern (default: *.test.{ts,js,tsx,jsx})
+  --json               Output JSON instead of text
+  --threshold <1-10>   Min flakiness score to report (default: 4)
+  --no-duplicates      Skip cross-file duplicate detection
+  --no-code-analysis   Skip code body analysis (descriptions only)
+  --help, -h           Show this help
+  --version, -v        Show version
+
+Examples:
+  testkit scan ./src/tests
+  testkit scan ./tests --pattern "*.spec.ts" --json
+  testkit scan . --threshold 6 --no-duplicates
+`);
+}
+
+function printVersion(): void {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf-8"));
+    console.log(`@iklab/testkit v${pkg.version}`);
+  } catch {
+    console.log("@iklab/testkit");
+  }
+}
+
+function emptyReport(): ScanReport {
+  return {
+    files: [],
+    flakyTests: [],
+    duplicates: [],
+    summary: {
+      filesScanned: 0,
+      testsFound: 0,
+      issuesFound: 0,
+      duplicatesFound: 0,
+      flakyTestsFound: 0,
+      skippedTests: 0,
+      focusedTests: 0,
+    },
+  };
+}
+
+// Run
+main();
diff --git a/src/reporter/json-reporter.ts b/src/reporter/json-reporter.ts
new file mode 100644
index 0000000..b65a23d
--- /dev/null
+++ b/src/reporter/json-reporter.ts
@@ -0,0 +1,9 @@
+import { ScanReport } from "../scanner/types";
+
+/**
+ * Format scan report as JSON string.
+ * Used with --json flag for CI/CD integration.
+ */
+export function formatJsonReport(report: ScanReport): string {
+  return JSON.stringify(report, null, 2);
+}
diff --git a/src/reporter/text-reporter.ts b/src/reporter/text-reporter.ts
new file mode 100644
index 0000000..a3f4295
--- /dev/null
+++ b/src/reporter/text-reporter.ts
@@ -0,0 +1,117 @@
+import { ScanReport, FileResult, FlakyTestResult, DuplicateTestPair, CodeIssue } from "../scanner/types";
+
+// ─── ANSI Colors (no dependency) ────────────────────────────────────
+
+const isTTY = process.stdout.isTTY === true;
+
+const color = {
+  reset: isTTY ? "\x1b[0m" : "",
+  bold: isTTY ? "\x1b[1m" : "",
+  dim: isTTY ? "\x1b[2m" : "",
+  red: isTTY ? "\x1b[31m" : "",
+  yellow: isTTY ? "\x1b[33m" : "",
+  green: isTTY ? "\x1b[32m" : "",
+  cyan: isTTY ? "\x1b[36m" : "",
+  magenta: isTTY ? "\x1b[35m" : "",
+};
+
+// ─── Public ─────────────────────────────────────────────────────────
+
+export function formatTextReport(report: ScanReport): string {
+  const lines: string[] = [];
+
+  lines.push("");
+  lines.push(`${color.bold}@iklab/testkit scan report${color.reset}`);
+  lines.push("=".repeat(40));
+  lines.push("");
+
+  // Per-file issues
+  for (const file of report.files) {
+    const issues = file.codeIssues;
+    const flakyInFile = report.flakyTests.filter((f) => f.filePath === file.filePath);
+    const skipped = file.tests.filter((t) => t.skipped);
+    const focused = file.tests.filter((t) => t.focused);
+
+    const fileIssueCount = issues.length + flakyInFile.length + skipped.length + focused.length;
+
+    if (file.parseError) {
+      lines.push(`${color.red}!${color.reset} ${color.bold}${file.relativePath}${color.reset} ${color.dim}(parse error)${color.reset}`);
+      lines.push(`  ${color.red}${file.parseError}${color.reset}`);
+      lines.push("");
+      continue;
+    }
+
+    if (fileIssueCount === 0) continue;
+
+    lines.push(`${color.cyan}>${color.reset} ${color.bold}${file.relativePath}${color.reset} ${color.dim}(${file.tests.length} tests)${color.reset}`);
+
+    // Flaky descriptions
+    for (const flaky of flakyInFile) {
+      lines.push(`  ${color.yellow}!${color.reset} ${color.yellow}[flaky:${flaky.score}]${color.reset} "${flaky.fullName}" ${color.dim}(line ${flaky.line})${color.reset}`);
+      for (const risk of flaky.risks) {
+        lines.push(`    ${color.dim}Risk: ${risk}${color.reset}`);
+      }
+      for (const suggestion of flaky.suggestions) {
+        lines.push(`    ${color.dim}-> ${suggestion}${color.reset}`);
+      }
+    }
+
+    // Code issues
+    for (const issue of issues) {
+      const icon = issue.type === "no-assertion" ? color.red + "!" + color.reset
+        : issue.type === "flaky-code" ? color.yellow + "!" + color.reset
+        : color.yellow + "!" + color.reset;
+
+      lines.push(`  ${icon} ${color.yellow}[${issue.type}]${color.reset} ${issue.message} ${color.dim}(line ${issue.line})${color.reset}`);
+      lines.push(`    ${color.dim}-> ${issue.suggestion}${color.reset}`);
+    }
+
+    // Focused tests
+    for (const t of focused) {
+      lines.push(`  ${color.red}!${color.reset} ${color.red}[focused]${color.reset} "${t.fullName}" is focused (.only) ${color.dim}(line ${t.line})${color.reset}`);
+      lines.push(`    ${color.dim}-> Remove .only before committing${color.reset}`);
+    }
+
+    // Skipped tests
+    for (const t of skipped) {
+      lines.push(`  ${color.yellow}!${color.reset} ${color.yellow}[skipped]${color.reset} "${t.fullName}" is skipped ${color.dim}(line ${t.line})${color.reset}`);
+      lines.push(`    ${color.dim}-> Fix or remove skipped test${color.reset}`);
+    }
+
+    lines.push("");
+  }
+
+  // Cross-file duplicates
+  if (report.duplicates.length > 0) {
+    lines.push(`${color.magenta}Duplicate test names${color.reset}`);
+    for (const dup of report.duplicates) {
+      lines.push(`  ${color.yellow}!${color.reset} ${color.dim}Similarity ${(dup.similarity * 100).toFixed(0)}%:${color.reset}`);
+      lines.push(`    "${dup.nameA}" ${color.dim}${dup.fileA}:${dup.lineA}${color.reset}`);
+      lines.push(`    "${dup.nameB}" ${color.dim}${dup.fileB}:${dup.lineB}${color.reset}`);
+    }
+    lines.push("");
+  }
+
+  // Summary
+  const s = report.summary;
+  const hasIssues = s.issuesFound > 0 || s.duplicatesFound > 0 || s.flakyTestsFound > 0 || s.focusedTests > 0;
+  const summaryColor = hasIssues ? color.yellow : color.green;
+
+  lines.push(`${color.bold}Summary${color.reset}`);
+  lines.push(`  ${color.dim}Files scanned:${color.reset}  ${s.filesScanned}`);
+  lines.push(`  ${color.dim}Tests found:${color.reset}    ${s.testsFound}`);
+
+  if (s.issuesFound > 0) lines.push(`  ${color.yellow}Code issues:${color.reset}    ${s.issuesFound}`);
+  if (s.flakyTestsFound > 0) lines.push(`  ${color.yellow}Flaky tests:${color.reset}    ${s.flakyTestsFound}`);
+  if (s.duplicatesFound > 0) lines.push(`  ${color.yellow}Duplicates:${color.reset}     ${s.duplicatesFound}`);
+  if (s.skippedTests > 0) lines.push(`  ${color.yellow}Skipped:${color.reset}        ${s.skippedTests}`);
+  if (s.focusedTests > 0) lines.push(`  ${color.red}Focused:${color.reset}        ${s.focusedTests}`);
+
+  if (!hasIssues) {
+    lines.push(`  ${color.green}No issues found.${color.reset}`);
+  }
+
+  lines.push("");
+
+  return lines.join("\n");
+}
diff --git a/src/scanner/ast-parser.ts b/src/scanner/ast-parser.ts
new file mode 100644
index 0000000..d3d98f4
--- /dev/null
+++ b/src/scanner/ast-parser.ts
@@ -0,0 +1,29 @@
+import * as acorn from "acorn";
+import { tsPlugin } from "@sveltejs/acorn-typescript";
+
+/**
+ * Parse a JavaScript or TypeScript file into an ESTree-compliant AST.
+ *
+ * Uses acorn with @sveltejs/acorn-typescript plugin for TS/JSX support.
+ * Returns null if parsing fails (caller handles gracefully).
+ */
+export function parseFile(source: string, filename: string): acorn.Node | null {
+  const isTypeScript = /\.tsx?$/.test(filename);
+
+  try {
+    const parser = isTypeScript
+      ? acorn.Parser.extend(tsPlugin() as any)
+      : acorn.Parser;
+
+    return parser.parse(source, {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      locations: true,
+      // Allow JSX in TSX/JSX files
+      ...(isTypeScript ? {} : {}),
+    });
+  } catch {
+    // Parse error — file might have syntax errors or unsupported syntax
+    return null;
+  }
+}
diff --git a/src/scanner/code-analyzer.ts b/src/scanner/code-analyzer.ts
new file mode 100644
index 0000000..66006ba
--- /dev/null
+++ b/src/scanner/code-analyzer.ts
@@ -0,0 +1,273 @@
+import type { Node } from "acorn";
+import { CodeIssue } from "./types";
+
+/** Test function names that contain test bodies to analyze */
+const TEST_BODY_FUNCTIONS = new Set(["it", "test", "xit", "xtest", "fit", "ftest"]);
+
+/** Assertion function names */
+const ASSERTION_FUNCTIONS = new Set(["expect", "assert", "should"]);
+
+/**
+ * Analyze test code bodies for quality issues.
+ *
+ * Detects:
+ * - Flaky code patterns (setTimeout, fetch without mock, Date.now, Math.random, etc.)
+ * - Missing assertions (test body with no expect/assert)
+ * - Conditional assertions (if (...) expect(...))
+ * - Focused/skipped tests (.only, .skip, x-prefixed, f-prefixed)
+ */
+export function analyzeCode(ast: Node): CodeIssue[] {
+  const issues: CodeIssue[] = [];
+  findTestBodies(ast, issues);
+  return issues;
+}
+
+// ─── Flaky Code Patterns ────────────────────────────────────────────
+
+interface FlakyPattern {
+  /** Identifier or member expression to match */
+  match: (node: any) => boolean;
+  message: string;
+  suggestion: string;
+}
+
+const FLAKY_PATTERNS: FlakyPattern[] = [
+  {
+    match: (n) => isCallTo(n, "setTimeout") || isCallTo(n, "setInterval"),
+    message: "setTimeout/setInterval in test body — timing dependency",
+    suggestion: "Use jest.useFakeTimers() or sinon.clock for deterministic timing",
+  },
+  {
+    match: (n) => isMemberCall(n, "Date", "now") || isNewExpression(n, "Date"),
+    message: "Date.now() or new Date() in test — time dependency",
+    suggestion: "Use jest.useFakeTimers() or freeze time with sinon.useFakeTimers()",
+  },
+  {
+    match: (n) => isMemberCall(n, "Math", "random"),
+    message: "Math.random() in test — non-deterministic output",
+    suggestion: "Seed the random generator or mock Math.random()",
+  },
+  {
+    match: (n) => isCallTo(n, "fetch") || isCallTo(n, "axios") || isMemberCall(n, "http", "get") || isMemberCall(n, "http", "request"),
+    message: "HTTP call in test body — external service dependency",
+    suggestion: "Mock HTTP calls with jest.mock, msw, or nock",
+  },
+  {
+    match: (n) => isMemberCall(n, "process", "env"),
+    message: "process.env access in test — environment dependency",
+    suggestion: "Use .env.test with fixed values or jest.replaceProperty",
+  },
+  {
+    match: (n) => isMemberCall(n, "fs", "readFileSync") || isMemberCall(n, "fs", "writeFileSync") ||
+                  isMemberCall(n, "fs", "readFile") || isMemberCall(n, "fs", "writeFile"),
+    message: "File system I/O in test — shared state risk",
+    suggestion: "Use temp directories (os.tmpdir) and cleanup in afterEach",
+  },
+];
+
+// ─── Test Body Discovery ────────────────────────────────────────────
+
+function findTestBodies(node: any, issues: CodeIssue[]): void {
+  if (!node || typeof node !== "object") return;
+
+  if (node.type === "CallExpression") {
+    const funcName = getCallName(node);
+
+    if (funcName && TEST_BODY_FUNCTIONS.has(funcName)) {
+      // Found a test body — analyze the callback
+      const callback = node.arguments?.[1];
+      if (callback && (callback.type === "ArrowFunctionExpression" || callback.type === "FunctionExpression")) {
+        analyzeTestBody(callback.body, node.loc?.start?.line ?? 0, issues);
+      }
+    }
+  }
+
+  // Recurse into child nodes
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "start" || key === "end" || key === "type") continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (item && typeof item === "object" && item.type) {
+          findTestBodies(item, issues);
+        }
+      }
+    } else if (child && typeof child === "object" && child.type) {
+      findTestBodies(child, issues);
+    }
+  }
+}
+
+function analyzeTestBody(body: any, testLine: number, issues: CodeIssue[]): void {
+  if (!body) return;
+
+  let hasAssertion = false;
+  let hasConditionalAssert = false;
+
+  walkBody(body, (node: any) => {
+    // Check for flaky patterns
+    for (const pattern of FLAKY_PATTERNS) {
+      if (pattern.match(node)) {
+        issues.push({
+          type: "flaky-code",
+          message: pattern.message,
+          line: node.loc?.start?.line ?? testLine,
+          suggestion: pattern.suggestion,
+        });
+      }
+    }
+
+    // Check for assertions
+    if (isAssertionCall(node)) {
+      hasAssertion = true;
+
+      // Check if assertion is inside an if/ternary (conditional assertion)
+      // We check this at the if-statement level in the parent walk
+    }
+
+    // Check for conditional assertions: if (...) { expect(...) }
+    if (node.type === "IfStatement") {
+      if (containsAssertion(node.consequent) || (node.alternate && containsAssertion(node.alternate))) {
+        hasConditionalAssert = true;
+      }
+    }
+  });
+
+  if (!hasAssertion) {
+    issues.push({
+      type: "no-assertion",
+      message: "Test has no assertions (no expect/assert calls)",
+      line: testLine,
+      suggestion: "Add expect() assertions to verify test behavior",
+    });
+  }
+
+  if (hasConditionalAssert) {
+    issues.push({
+      type: "conditional-assert",
+      message: "Assertion inside conditional (if/else) — may not always run",
+      line: testLine,
+      suggestion: "Move assertions out of conditionals or split into separate tests",
+    });
+  }
+}
+
+// ─── AST Helpers ────────────────────────────────────────────────────
+
+function walkBody(node: any, visitor: (n: any) => void): void {
+  if (!node || typeof node !== "object") return;
+  visitor(node);
+
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "start" || key === "end" || key === "type") continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (item && typeof item === "object" && item.type) {
+          walkBody(item, visitor);
+        }
+      }
+    } else if (child && typeof child === "object" && child.type) {
+      walkBody(child, visitor);
+    }
+  }
+}
+
+/** Check if node is a call to a global function: setTimeout(...) */
+function isCallTo(node: any, name: string): boolean {
+  return (
+    node.type === "CallExpression" &&
+    node.callee?.type === "Identifier" &&
+    node.callee.name === name
+  );
+}
+
+/** Check if node is a member call: obj.method(...) */
+function isMemberCall(node: any, obj: string, method: string): boolean {
+  return (
+    node.type === "CallExpression" &&
+    node.callee?.type === "MemberExpression" &&
+    node.callee.object?.type === "Identifier" &&
+    node.callee.object.name === obj &&
+    node.callee.property?.name === method
+  );
+}
+
+/** Check if node is: new Constructor() */
+function isNewExpression(node: any, name: string): boolean {
+  return (
+    node.type === "NewExpression" &&
+    node.callee?.type === "Identifier" &&
+    node.callee.name === name
+  );
+}
+
+/** Check if node is a member access: obj.prop (not a call) */
+function isMemberAccess(node: any, obj: string, prop: string): boolean {
+  return (
+    node.type === "MemberExpression" &&
+    node.object?.type === "Identifier" &&
+    node.object.name === obj &&
+    node.property?.name === prop
+  );
+}
+
+/** Check if node is an assertion call: expect(...), assert(...) */
+function isAssertionCall(node: any): boolean {
+  if (node.type !== "CallExpression") return false;
+
+  // expect(...)
+  if (node.callee?.type === "Identifier" && ASSERTION_FUNCTIONS.has(node.callee.name)) {
+    return true;
+  }
+
+  // expect(...).toBe(...) — the outer MemberExpression call
+  if (node.callee?.type === "MemberExpression") {
+    // Walk the chain: expect(x).toBe(y) → callee is MemberExpression, callee.object is CallExpression
+    let current = node.callee;
+    while (current?.type === "MemberExpression") {
+      current = current.object;
+    }
+    if (current?.type === "CallExpression" && current.callee?.type === "Identifier") {
+      if (ASSERTION_FUNCTIONS.has(current.callee.name)) return true;
+    }
+  }
+
+  return false;
+}
+
+/** Check if a subtree contains any assertion call */
+function containsAssertion(node: any): boolean {
+  if (!node || typeof node !== "object") return false;
+
+  if (isAssertionCall(node)) return true;
+
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "start" || key === "end" || key === "type") continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (containsAssertion(item)) return true;
+      }
+    } else if (containsAssertion(child)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function getCallName(node: any): string | null {
+  const callee = node.callee;
+  if (!callee) return null;
+
+  // it(...), test(...)
+  if (callee.type === "Identifier") return callee.name;
+
+  // it.skip(...), test.only(...)
+  if (callee.type === "MemberExpression" && callee.object?.type === "Identifier") {
+    return callee.object.name;
+  }
+
+  return null;
+}
diff --git a/src/scanner/file-discovery.ts b/src/scanner/file-discovery.ts
new file mode 100644
index 0000000..f78c835
--- /dev/null
+++ b/src/scanner/file-discovery.ts
@@ -0,0 +1,103 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, extname, basename } from "node:path";
+
+/** Directories to always skip */
+const EXCLUDED_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".cache",
+  ".nuxt",
+  ".output",
+  "__snapshots__",
+]);
+
+/** Default test file extensions */
+const TEST_EXTENSIONS = new Set([".ts", ".js", ".tsx", ".jsx", ".mts", ".mjs"]);
+
+/** Default test file patterns (checked against basename) */
+const TEST_PATTERNS = [
+  /\.test\./,
+  /\.spec\./,
+  /_test\./,
+  /_spec\./,
+];
+
+/**
+ * Recursively discovers test files in a directory.
+ *
+ * @param rootDir - Absolute path to scan
+ * @param customPattern - Optional regex pattern override (e.g., from --pattern flag)
+ * @returns Array of absolute file paths
+ */
+export function discoverTestFiles(rootDir: string, customPattern?: string): string[] {
+  const files: string[] = [];
+  const pattern = customPattern ? globToRegex(customPattern) : null;
+
+  walkDir(rootDir, rootDir, files, pattern);
+
+  return files.sort();
+}
+
+function walkDir(dir: string, rootDir: string, files: string[], pattern: RegExp | null): void {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    // Permission denied or inaccessible — skip silently
+    return;
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") && entry.name !== ".") continue;
+
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry.name)) continue;
+      walkDir(fullPath, rootDir, files, pattern);
+    } else if (entry.isFile()) {
+      if (isTestFile(entry.name, pattern)) {
+        files.push(fullPath);
+      }
+    }
+  }
+}
+
+function isTestFile(filename: string, customPattern: RegExp | null): boolean {
+  const ext = extname(filename);
+  if (!TEST_EXTENSIONS.has(ext)) return false;
+
+  if (customPattern) {
+    return customPattern.test(filename);
+  }
+
+  return TEST_PATTERNS.some((p) => p.test(filename));
+}
+
+/**
+ * Converts a simple glob pattern to regex.
+ * Supports: *, ?, {a,b}
+ * Examples: "*.test.ts" → /^.*\.test\.ts$/
+ */
+function globToRegex(glob: string): RegExp {
+  let regex = glob
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&") // Escape special regex chars
+    .replace(/\*/g, ".*")                   // * → .*
+    .replace(/\?/g, ".");                   // ? → .
+
+  // Handle {a,b} brace expansion
+  regex = regex.replace(/\\{([^}]+)\\}/g, (_, group) => {
+    return `(${group.split(",").join("|")})`;
+  });
+
+  return new RegExp(`^${regex}$`);
+}
+
+/** Get relative path for display */
+export function getRelativePath(filePath: string, rootDir: string): string {
+  return relative(rootDir, filePath);
+}
diff --git a/src/scanner/test-extractor.ts b/src/scanner/test-extractor.ts
new file mode 100644
index 0000000..2065893
--- /dev/null
+++ b/src/scanner/test-extractor.ts
@@ -0,0 +1,154 @@
+import type { Node } from "acorn";
+import { ExtractedTest } from "./types";
+
+/** Test function names we recognize */
+const TEST_FUNCTIONS = new Set(["describe", "it", "test"]);
+const SKIP_VARIANTS = new Set(["xdescribe", "xit", "xtest"]);
+const FOCUS_VARIANTS = new Set(["fdescribe", "fit", "ftest"]);
+
+/**
+ * Extract test blocks (describe/it/test) from an ESTree AST.
+ *
+ * Handles:
+ * - describe("name", () => { ... })
+ * - it("name", () => { ... })
+ * - test("name", () => { ... })
+ * - describe.skip / it.skip / test.skip
+ * - describe.only / it.only / test.only
+ * - xdescribe / xit / xtest
+ * - fdescribe / fit / ftest
+ * - Nested describes → builds fullName with " > " separator
+ */
+export function extractTests(ast: Node): ExtractedTest[] {
+  const results: ExtractedTest[] = [];
+  walkNode(ast, [], results);
+  return results;
+}
+
+function walkNode(node: any, ancestors: string[], results: ExtractedTest[]): void {
+  if (!node || typeof node !== "object") return;
+
+  if (node.type === "CallExpression") {
+    const info = parseTestCall(node);
+    if (info) {
+      const test: ExtractedTest = {
+        fullName: [...ancestors, info.name].join(" > "),
+        name: info.name,
+        line: node.loc?.start?.line ?? 0,
+        type: info.type,
+        skipped: info.skipped,
+        focused: info.focused,
+        ancestors: [...ancestors],
+      };
+      results.push(test);
+
+      // If it's a describe, recurse into the callback body with this name as ancestor
+      if (info.type === "describe" && info.bodyNode) {
+        walkNode(info.bodyNode, [...ancestors, info.name], results);
+        return; // Don't walk children again
+      }
+    }
+  }
+
+  // Walk all child nodes
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "start" || key === "end" || key === "type") continue;
+
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (item && typeof item === "object" && item.type) {
+          walkNode(item, ancestors, results);
+        }
+      }
+    } else if (child && typeof child === "object" && child.type) {
+      walkNode(child, ancestors, results);
+    }
+  }
+}
+
+interface TestCallInfo {
+  name: string;
+  type: "describe" | "it" | "test";
+  skipped: boolean;
+  focused: boolean;
+  bodyNode: any | null; // Callback body for describe blocks
+}
+
+function parseTestCall(node: any): TestCallInfo | null {
+  const callee = node.callee;
+  if (!callee) return null;
+
+  let funcName: string | null = null;
+  let skipped = false;
+  let focused = false;
+
+  // Case 1: describe("name", fn) / it("name", fn) / test("name", fn)
+  if (callee.type === "Identifier") {
+    const name = callee.name;
+    if (TEST_FUNCTIONS.has(name)) {
+      funcName = name;
+    } else if (SKIP_VARIANTS.has(name)) {
+      funcName = name.replace(/^x/, "");
+      skipped = true;
+    } else if (FOCUS_VARIANTS.has(name)) {
+      funcName = name.replace(/^f/, "");
+      focused = true;
+    }
+  }
+
+  // Case 2: describe.skip("name", fn) / it.only("name", fn) / test.each(...)
+  if (callee.type === "MemberExpression" && callee.object?.type === "Identifier") {
+    const objName = callee.object.name;
+    const propName = callee.property?.name;
+
+    if (TEST_FUNCTIONS.has(objName) || SKIP_VARIANTS.has(objName) || FOCUS_VARIANTS.has(objName)) {
+      funcName = TEST_FUNCTIONS.has(objName) ? objName : objName.replace(/^[xf]/, "");
+
+      if (propName === "skip") skipped = true;
+      else if (propName === "only") focused = true;
+      else if (propName === "each" || propName === "todo") {
+        // test.each and test.todo — we still record them
+        // For test.each, the actual CallExpression is the outer one
+      }
+    }
+  }
+
+  if (!funcName) return null;
+
+  // Extract test name from first argument (must be a string literal)
+  const firstArg = node.arguments?.[0];
+  const name = extractStringLiteral(firstArg);
+  if (!name) return null;
+
+  // Normalize type
+  const type = funcName === "describe" ? "describe" : funcName === "it" ? "it" : "test";
+
+  // For describe blocks, find the callback body for nested extraction
+  let bodyNode: any = null;
+  if (type === "describe") {
+    const callback = node.arguments?.[1];
+    if (callback && (callback.type === "ArrowFunctionExpression" || callback.type === "FunctionExpression")) {
+      bodyNode = callback.body;
+    }
+  }
+
+  return { name, type, skipped, focused, bodyNode };
+}
+
+/** Extract string value from AST node (string literal or template literal without expressions) */
+function extractStringLiteral(node: any): string | null {
+  if (!node) return null;
+
+  // "string" or 'string'
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value;
+  }
+
+  // `template string` without expressions
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0 && node.quasis.length === 1) {
+    return node.quasis[0].value.cooked;
+  }
+
+  return null;
+}
diff --git a/src/scanner/types.ts b/src/scanner/types.ts
new file mode 100644
index 0000000..81582a2
--- /dev/null
+++ b/src/scanner/types.ts
@@ -0,0 +1,106 @@
+/** Represents a single test block (describe/it/test) found in a file */
+export interface ExtractedTest {
+  /** Full test name including parent describes: "Auth > Login > should validate email" */
+  fullName: string;
+  /** Direct test name from it/test call: "should validate email" */
+  name: string;
+  /** Line number in source file (1-based) */
+  line: number;
+  /** "describe" | "it" | "test" */
+  type: "describe" | "it" | "test";
+  /** Whether test is skipped (.skip, xit, xtest, xdescribe) */
+  skipped: boolean;
+  /** Whether test is focused (.only, fit, fdescribe) */
+  focused: boolean;
+  /** Parent describe names (outermost first) */
+  ancestors: string[];
+}
+
+/** A flaky pattern detected in test code body */
+export interface CodeIssue {
+  /** Issue category */
+  type: "flaky-code" | "no-assertion" | "conditional-assert" | "focused" | "skipped";
+  /** Human-readable description */
+  message: string;
+  /** Line number (1-based) */
+  line: number;
+  /** Actionable suggestion */
+  suggestion: string;
+}
+
+/** Results for a single scanned file */
+export interface FileResult {
+  /** Absolute file path */
+  filePath: string;
+  /** Relative path for display */
+  relativePath: string;
+  /** All extracted tests */
+  tests: ExtractedTest[];
+  /** Code-level issues found */
+  codeIssues: CodeIssue[];
+  /** Parse errors (file couldn't be parsed) */
+  parseError?: string;
+}
+
+/** Description-level flakiness result */
+export interface FlakyTestResult {
+  /** Full test name */
+  fullName: string;
+  /** File path */
+  filePath: string;
+  /** Line number */
+  line: number;
+  /** Flakiness score 1-10 */
+  score: number;
+  /** Risk patterns detected */
+  risks: string[];
+  /** Suggestions */
+  suggestions: string[];
+}
+
+/** Duplicate test pair found across files */
+export interface DuplicateTestPair {
+  nameA: string;
+  nameB: string;
+  fileA: string;
+  lineA: number;
+  fileB: string;
+  lineB: number;
+  similarity: number;
+}
+
+/** Complete scan report */
+export interface ScanReport {
+  /** Files that were scanned */
+  files: FileResult[];
+  /** Flaky test descriptions (score >= threshold) */
+  flakyTests: FlakyTestResult[];
+  /** Duplicate test names across files */
+  duplicates: DuplicateTestPair[];
+  /** Summary statistics */
+  summary: {
+    filesScanned: number;
+    testsFound: number;
+    issuesFound: number;
+    duplicatesFound: number;
+    flakyTestsFound: number;
+    skippedTests: number;
+    focusedTests: number;
+  };
+}
+
+/** CLI options parsed from arguments */
+export interface ScanOptions {
+  /** Root directory to scan */
+  dir: string;
+  /** File pattern (e.g., "*.test.ts") */
+  pattern: string;
+  /** Output format */
+  format: "text" | "json";
+  /** Minimum flakiness score to report (1-10) */
+  threshold: number;
+  /** Skip duplicate detection */
+  noDuplicates: boolean;
+  /** Skip code body analysis */
+  noCodeAnalysis: boolean;
+}
diff --git a/tsup.config.ts b/tsup.config.ts
index 00c5953..22afefe 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -1,10 +1,26 @@
 import { defineConfig } from "tsup";
 
-export default defineConfig({
-  entry: ["src/index.ts"],
-  format: ["esm", "cjs"],
-  dts: true,
-  clean: true,
-  splitting: false,
-  sourcemap: false,
-});
+export default defineConfig([
+  // Library (ESM + CJS with types) — keeps acorn as external dependency
+  {
+    entry: ["src/index.ts"],
+    format: ["esm", "cjs"],
+    dts: true,
+    clean: true,
+    splitting: false,
+    sourcemap: false,
+  },
+  // CLI (CJS only, with shebang) — bundles all dependencies for standalone execution
+  {
+    entry: ["src/cli.ts"],
+    format: ["cjs"],
+    dts: false,
+    clean: false,
+    splitting: false,
+    sourcemap: false,
+    noExternal: [/.*/], // Bundle everything including acorn for standalone CLI
+    banner: {
+      js: "#!/usr/bin/env node",
+    },
+  },
+]);

From fa015d1dde21e7628c90ec6eff3a453515641c9c Mon Sep 17 00:00:00 2001
From: Ihor Kosheliev <137728460+i-kosheliev@users.noreply.github.com>
Date: Tue, 14 Apr 2026 02:46:53 +0300
Subject: [PATCH 2/4] =?UTF-8?q?fix:=20audit=20fixes=20=E2=80=94=20process.?=
 =?UTF-8?q?env=20detection,=20symlink=20guard,=20file=20size=20limit?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. process.env: changed isMemberCall to isMemberAccess — was checking
   for process.env() (CallExpression) instead of process.env.X
   (MemberExpression). Pattern never triggered before this fix.
2. Symlink cycle protection: walkDir now tracks visited real paths
   via realpathSync() + Set. Max depth 50 prevents stack overflow.
3. File size limit: CLI skips files > 5MB to prevent OOM on huge
   generated files.
4. New test: process.env detection in flaky fixture.

151 tests passing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/__tests__/fixtures/flaky.test.ts |  5 +++++
 src/__tests__/scanner.test.ts        |  9 +++++++++
 src/cli.ts                           | 15 +++++++++++++-
 src/scanner/code-analyzer.ts         |  2 +-
 src/scanner/file-discovery.ts        | 29 +++++++++++++++++++++++++---
 5 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/src/__tests__/fixtures/flaky.test.ts b/src/__tests__/fixtures/flaky.test.ts
index 4701fc2..f76924a 100644
--- a/src/__tests__/fixtures/flaky.test.ts
+++ b/src/__tests__/fixtures/flaky.test.ts
@@ -20,4 +20,9 @@ describe("API Integration", () => {
     const id = Math.random().toString(36);
     expect(id).toBeTruthy();
   });
+
+  it("should use environment config", () => {
+    const apiUrl = process.env.API_URL;
+    expect(apiUrl).toBeDefined();
+  });
 });
diff --git a/src/__tests__/scanner.test.ts b/src/__tests__/scanner.test.ts
index cd29d09..a8a6598 100644
--- a/src/__tests__/scanner.test.ts
+++ b/src/__tests__/scanner.test.ts
@@ -146,6 +146,15 @@ describe("code-analyzer", () => {
     expect(randomIssue).toBeDefined();
   });
 
+  it("detects process.env access in test body", () => {
+    const ast = parseFixture("flaky.test.ts")!;
+    const issues = analyzeCode(ast);
+
+    const envIssue = issues.find((i) => i.message.includes("process.env"));
+    expect(envIssue).toBeDefined();
+    expect(envIssue!.type).toBe("flaky-code");
+  });
+
   it("detects missing assertions (no expect)", () => {
     const ast = parseFixture("quality-issues.test.ts")!;
     const issues = analyzeCode(ast);
diff --git a/src/cli.ts b/src/cli.ts
index 18f4bc9..5c80161 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -7,8 +7,11 @@
  * missing assertions, and other quality issues.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { resolve, isAbsolute } from "node:path";
+
+/** Max file size to read (5MB) — prevents OOM on huge generated files */
+const MAX_FILE_SIZE = 5 * 1024 * 1024;
 import { discoverTestFiles, getRelativePath } from "./scanner/file-discovery";
 import { parseFile } from "./scanner/ast-parser";
 import { extractTests } from "./scanner/test-extractor";
@@ -171,6 +174,16 @@ function analyzeFile(filePath: string, rootDir: string, options: ScanOptions): F
 
   let source: string;
   try {
+    const stat = statSync(filePath);
+    if (stat.size > MAX_FILE_SIZE) {
+      return {
+        filePath,
+        relativePath,
+        tests: [],
+        codeIssues: [],
+        parseError: `File too large (${(stat.size / 1024 / 1024).toFixed(1)}MB > 5MB limit)`,
+      };
+    }
     source = readFileSync(filePath, "utf-8");
   } catch {
     return {
diff --git a/src/scanner/code-analyzer.ts b/src/scanner/code-analyzer.ts
index 66006ba..329a91c 100644
--- a/src/scanner/code-analyzer.ts
+++ b/src/scanner/code-analyzer.ts
@@ -53,7 +53,7 @@ const FLAKY_PATTERNS: FlakyPattern[] = [
     suggestion: "Mock HTTP calls with jest.mock, msw, or nock",
   },
   {
-    match: (n) => isMemberCall(n, "process", "env"),
+    match: (n) => isMemberAccess(n, "process", "env"),
     message: "process.env access in test — environment dependency",
     suggestion: "Use .env.test with fixed values or jest.replaceProperty",
   },
diff --git a/src/scanner/file-discovery.ts b/src/scanner/file-discovery.ts
index f78c835..aeaa1b9 100644
--- a/src/scanner/file-discovery.ts
+++ b/src/scanner/file-discovery.ts
@@ -1,4 +1,4 @@
-import { readdirSync, statSync } from "node:fs";
+import { readdirSync, statSync, realpathSync } from "node:fs";
 import { join, relative, extname, basename } from "node:path";
 
 /** Directories to always skip */
@@ -42,7 +42,30 @@ export function discoverTestFiles(rootDir: string, customPattern?: string): stri
   return files.sort();
 }
 
-function walkDir(dir: string, rootDir: string, files: string[], pattern: RegExp | null): void {
+/** Max recursion depth to prevent stack overflow on deeply nested dirs */
+const MAX_DEPTH = 50;
+
+function walkDir(
+  dir: string,
+  rootDir: string,
+  files: string[],
+  pattern: RegExp | null,
+  visited: Set<string> = new Set(),
+  depth: number = 0
+): void {
+  if (depth > MAX_DEPTH) return;
+
+  // Resolve real path to detect symlink cycles
+  let realPath: string;
+  try {
+    realPath = realpathSync(dir);
+  } catch {
+    return; // Broken symlink or permission denied
+  }
+
+  if (visited.has(realPath)) return; // Symlink cycle detected
+  visited.add(realPath);
+
   let entries;
   try {
     entries = readdirSync(dir, { withFileTypes: true });
@@ -58,7 +81,7 @@ function walkDir(dir: string, rootDir: string, files: string[], pattern: RegExp
 
     if (entry.isDirectory()) {
       if (EXCLUDED_DIRS.has(entry.name)) continue;
-      walkDir(fullPath, rootDir, files, pattern);
+      walkDir(fullPath, rootDir, files, pattern, visited, depth + 1);
     } else if (entry.isFile()) {
       if (isTestFile(entry.name, pattern)) {
         files.push(fullPath);

From e2f01dc49126f30de8f2fe4d119736f960f6dba5 Mon Sep 17 00:00:00 2001
From: Ihor Kosheliev <137728460+i-kosheliev@users.noreply.github.com>
Date: Tue, 14 Apr 2026 03:02:39 +0300
Subject: [PATCH 3/4] test: add globToRegex, reporter, and process.env tests
 AB#434

9 new tests:
- globToRegex: wildcard, question mark, dot escaping, exact match
- text-reporter: header, clean report, summary stats
- json-reporter: valid JSON, all sections present

Also exported globToRegex for testing.
160 total tests passing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/__tests__/scanner.test.ts | 86 +++++++++++++++++++++++++++++++++--
 src/scanner/file-discovery.ts |  3 +-
 2 files changed, 85 insertions(+), 4 deletions(-)

diff --git a/src/__tests__/scanner.test.ts b/src/__tests__/scanner.test.ts
index a8a6598..150e2bc 100644
--- a/src/__tests__/scanner.test.ts
+++ b/src/__tests__/scanner.test.ts
@@ -3,7 +3,10 @@ import { join } from "node:path";
 import { parseFile } from "../scanner/ast-parser";
 import { extractTests } from "../scanner/test-extractor";
 import { analyzeCode } from "../scanner/code-analyzer";
-import { discoverTestFiles, getRelativePath } from "../scanner/file-discovery";
+import { discoverTestFiles, getRelativePath, globToRegex } from "../scanner/file-discovery";
+import { formatTextReport } from "../reporter/text-reporter";
+import { formatJsonReport } from "../reporter/json-reporter";
+import type { ScanReport } from "../scanner/types";
 
 const FIXTURES = join(__dirname, "fixtures");
 
@@ -219,11 +222,88 @@ describe("file-discovery", () => {
   });
 
   it("excludes node_modules", () => {
-    // discoverTestFiles from project root should not include node_modules
     const root = join(__dirname, "../..");
     const files = discoverTestFiles(root);
-
     const inNodeModules = files.filter((f) => f.includes("node_modules"));
     expect(inNodeModules).toHaveLength(0);
   });
 });
+
+// ─── globToRegex ────────────────────────────────────────────────────
+
+describe("globToRegex", () => {
+  it("matches simple wildcard pattern", () => {
+    const re = globToRegex("*.test.ts");
+    expect(re.test("auth.test.ts")).toBe(true);
+    expect(re.test("login.test.ts")).toBe(true);
+    expect(re.test("auth.spec.ts")).toBe(false);
+  });
+
+  it("matches question mark as single char", () => {
+    const re = globToRegex("test?.ts");
+    expect(re.test("test1.ts")).toBe(true);
+    expect(re.test("testA.ts")).toBe(true);
+    expect(re.test("test12.ts")).toBe(false);
+  });
+
+  it("escapes dots correctly", () => {
+    const re = globToRegex("*.test.ts");
+    expect(re.test("authXtestXts")).toBe(false); // dots must be literal
+  });
+
+  it("handles pattern without wildcards", () => {
+    const re = globToRegex("exact.test.ts");
+    expect(re.test("exact.test.ts")).toBe(true);
+    expect(re.test("other.test.ts")).toBe(false);
+  });
+});
+
+// ─── Reporters ──────────────────────────────────────────────────────
+
+function makeEmptyReport(): ScanReport {
+  return {
+    files: [],
+    flakyTests: [],
+    duplicates: [],
+    summary: { filesScanned: 0, testsFound: 0, issuesFound: 0, duplicatesFound: 0, flakyTestsFound: 0, skippedTests: 0, focusedTests: 0 },
+  };
+}
+
+describe("text-reporter", () => {
+  it("includes header", () => {
+    const output = formatTextReport(makeEmptyReport());
+    expect(output).toContain("@iklab/testkit scan report");
+  });
+
+  it("shows 'No issues found' for clean report", () => {
+    const output = formatTextReport(makeEmptyReport());
+    expect(output).toContain("No issues found");
+  });
+
+  it("shows summary stats", () => {
+    const report = makeEmptyReport();
+    report.summary.filesScanned = 5;
+    report.summary.testsFound = 42;
+    const output = formatTextReport(report);
+    expect(output).toContain("5");
+    expect(output).toContain("42");
+  });
+});
+
+describe("json-reporter", () => {
+  it("produces valid JSON", () => {
+    const output = formatJsonReport(makeEmptyReport());
+    const parsed = JSON.parse(output);
+    expect(parsed.files).toEqual([]);
+    expect(parsed.summary.filesScanned).toBe(0);
+  });
+
+  it("includes all report sections", () => {
+    const output = formatJsonReport(makeEmptyReport());
+    const parsed = JSON.parse(output);
+    expect(parsed).toHaveProperty("files");
+    expect(parsed).toHaveProperty("flakyTests");
+    expect(parsed).toHaveProperty("duplicates");
+    expect(parsed).toHaveProperty("summary");
+  });
+});
diff --git a/src/scanner/file-discovery.ts b/src/scanner/file-discovery.ts
index aeaa1b9..bfb0b67 100644
--- a/src/scanner/file-discovery.ts
+++ b/src/scanner/file-discovery.ts
@@ -106,7 +106,8 @@ function isTestFile(filename: string, customPattern: RegExp | null): boolean {
  * Supports: *, ?, {a,b}
  * Examples: "*.test.ts" → /^.*\.test\.ts$/
  */
-function globToRegex(glob: string): RegExp {
+/** @internal Exported for testing only */
+export function globToRegex(glob: string): RegExp {
   let regex = glob
     .replace(/[.+^${}()|[\]\\]/g, "\\$&") // Escape special regex chars
     .replace(/\*/g, ".*")                   // * → .*

From 7a8f329ad3dda2f0615245baa53dc10c72dbdac6 Mon Sep 17 00:00:00 2001
From: Ihor Kosheliev <137728460+i-kosheliev@users.noreply.github.com>
Date: Thu, 16 Apr 2026 18:58:15 +0300
Subject: [PATCH 4/4] =?UTF-8?q?feat:=20v1.1.0=20=E2=80=94=20coverage(),=20?=
 =?UTF-8?q?suggest(),=20boundaries.custom()?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New features:
- coverage(tests, requirements) — check requirements coverage with Jaccard similarity
- suggest(description) — pattern-based test improvement suggestions (12 patterns)
- boundaries.custom(rules) — define domain-specific valid/invalid/boundary values

180 tests, zero dependencies, TypeScript-first.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 package.json                     |  2 +-
 src/__tests__/boundaries.test.ts | 36 ++++++++++++++++++
 src/__tests__/coverage.test.ts   | 64 ++++++++++++++++++++++++++++++++
 src/__tests__/suggest.test.ts    | 43 +++++++++++++++++++++
 src/boundaries.ts                | 10 +++++
 src/coverage.ts                  | 48 ++++++++++++++++++++++++
 src/index.ts                     |  5 +++
 src/suggest.ts                   | 52 ++++++++++++++++++++++++++
 src/types.ts                     | 20 ++++++++++
 9 files changed, 279 insertions(+), 1 deletion(-)
 create mode 100644 src/__tests__/coverage.test.ts
 create mode 100644 src/__tests__/suggest.test.ts
 create mode 100644 src/coverage.ts
 create mode 100644 src/suggest.ts

diff --git a/package.json b/package.json
index 28c8399..98f4e84 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@iklab/testkit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Test quality toolkit — boundary values, flakiness prediction, duplicate detection, static test scanner.",
   "author": "Ihor Kosheliev",
   "license": "MIT",
diff --git a/src/__tests__/boundaries.test.ts b/src/__tests__/boundaries.test.ts
index 1d2f105..a28f9e9 100644
--- a/src/__tests__/boundaries.test.ts
+++ b/src/__tests__/boundaries.test.ts
@@ -464,3 +464,39 @@ describe("boundaries — structure", () => {
     }
   });
 });
+
+describe("boundaries.custom", () => {
+  it("returns provided values", () => {
+    const result = boundaries.custom({
+      valid: [18, 25, 65],
+      invalid: [-1, 0, 17, 151],
+      boundary: [18, 150],
+    });
+    expect(result.valid).toEqual([18, 25, 65]);
+    expect(result.invalid).toEqual([-1, 0, 17, 151]);
+    expect(result.boundary).toEqual([18, 150]);
+  });
+
+  it("defaults boundary to empty array", () => {
+    const result = boundaries.custom({
+      valid: ["a"],
+      invalid: [""],
+    });
+    expect(result.boundary).toEqual([]);
+  });
+
+  it("throws on missing valid array", () => {
+    expect(() => boundaries.custom({ valid: null as any, invalid: [] })).toThrow(TypeError);
+  });
+
+  it("throws on missing invalid array", () => {
+    expect(() => boundaries.custom({ valid: [], invalid: null as any })).toThrow(TypeError);
+  });
+
+  it("works with testEach", () => {
+    const { testEach } = require("../test-each");
+    const result = boundaries.custom({ valid: [1], invalid: [0], boundary: [1] });
+    const rows = testEach(result);
+    expect(rows.length).toBeGreaterThan(0);
+  });
+});
diff --git a/src/__tests__/coverage.test.ts b/src/__tests__/coverage.test.ts
new file mode 100644
index 0000000..a8d51d9
--- /dev/null
+++ b/src/__tests__/coverage.test.ts
@@ -0,0 +1,64 @@
+import { coverage } from "../coverage";
+
+describe("coverage", () => {
+  it("matches tests to requirements", () => {
+    const result = coverage(
+      ["should login with valid credentials", "should show error for wrong password"],
+      ["User can login", "User sees error on invalid password", "User can reset password"],
+      { threshold: 0.2 }
+    );
+    expect(result.coveragePercent).toBe(67);
+    expect(result.covered).toHaveLength(2);
+    expect(result.uncovered).toEqual(["User can reset password"]);
+  });
+
+  it("returns 100% when all requirements covered", () => {
+    const result = coverage(
+      ["should create user", "should delete user"],
+      ["Create user", "Delete user"]
+    );
+    expect(result.coveragePercent).toBe(100);
+    expect(result.uncovered).toHaveLength(0);
+  });
+
+  it("returns 0% when nothing matches", () => {
+    const result = coverage(
+      ["should render homepage"],
+      ["User can upload avatar"]
+    );
+    expect(result.coveragePercent).toBe(0);
+    expect(result.uncovered).toHaveLength(1);
+  });
+
+  it("handles empty arrays", () => {
+    expect(coverage([], []).coveragePercent).toBe(100);
+    expect(coverage(["test"], []).coveragePercent).toBe(100);
+    expect(coverage([], ["req"]).coveragePercent).toBe(0);
+  });
+
+  it("respects custom threshold", () => {
+    const result = coverage(
+      ["should show products"],
+      ["Display product catalog"],
+      { threshold: 0.5 }
+    );
+    // Higher threshold = fewer matches
+    expect(result.coveragePercent).toBeLessThanOrEqual(100);
+  });
+
+  it("provides mapping with matched tests", () => {
+    const result = coverage(
+      ["should create user account", "should validate email"],
+      ["User registration"],
+      { threshold: 0.2 }
+    );
+    expect(result.mapping).toHaveLength(1);
+    expect(result.mapping[0].requirement).toBe("User registration");
+    expect(result.mapping[0].covered).toBe(true);
+  });
+
+  it("throws on invalid input", () => {
+    expect(() => coverage(null as any, [])).toThrow(TypeError);
+    expect(() => coverage([], null as any)).toThrow(TypeError);
+  });
+});
diff --git a/src/__tests__/suggest.test.ts b/src/__tests__/suggest.test.ts
new file mode 100644
index 0000000..5e7fa1a
--- /dev/null
+++ b/src/__tests__/suggest.test.ts
@@ -0,0 +1,43 @@
+import { suggest } from "../suggest";
+
+describe("suggest", () => {
+  it("suggests negative case for create operations", () => {
+    const result = suggest("should create a new user");
+    expect(result.suggestions.some(s => s.includes("negative"))).toBe(true);
+  });
+
+  it("suggests auth for login-related tests", () => {
+    const result = suggest("should login with valid credentials");
+    expect(result.suggestions.some(s => s.includes("auth"))).toBe(true);
+  });
+
+  it("suggests boundary for search operations", () => {
+    const result = suggest("should search products by name");
+    expect(result.suggestions.some(s => s.includes("boundary") || s.includes("special characters"))).toBe(true);
+  });
+
+  it("suggests file edge cases for upload operations", () => {
+    const result = suggest("should upload user avatar");
+    expect(result.suggestions.some(s => s.includes("file") || s.includes("oversized"))).toBe(true);
+  });
+
+  it("suggests error handling for payment operations", () => {
+    const result = suggest("should process payment checkout");
+    expect(result.suggestions.some(s => s.includes("error") || s.includes("fail"))).toBe(true);
+  });
+
+  it("returns generic suggestions for vague descriptions", () => {
+    const result = suggest("should work");
+    expect(result.suggestions.length).toBeGreaterThan(0);
+  });
+
+  it("returns generic suggestions for empty input", () => {
+    const result = suggest("");
+    expect(result.suggestions).toHaveLength(4);
+  });
+
+  it("score reflects number of suggestions", () => {
+    const result = suggest("should create user");
+    expect(result.score).toBe(result.suggestions.length);
+  });
+});
diff --git a/src/boundaries.ts b/src/boundaries.ts
index 31980a1..f382b8d 100644
--- a/src/boundaries.ts
+++ b/src/boundaries.ts
@@ -282,4 +282,14 @@ export const boundaries = {
   password: passwordBoundaries,
   phone: phoneBoundaries,
   uuid: uuidBoundaries,
+  custom(rules: { valid: unknown[]; invalid: unknown[]; boundary?: unknown[] }): BoundaryResult {
+    if (!rules || !Array.isArray(rules.valid) || !Array.isArray(rules.invalid)) {
+      throw new TypeError("custom() requires { valid: unknown[], invalid: unknown[] }");
+    }
+    return {
+      valid: [...rules.valid],
+      invalid: [...rules.invalid],
+      boundary: rules.boundary ? [...rules.boundary] : [],
+    };
+  },
 };
diff --git a/src/coverage.ts b/src/coverage.ts
new file mode 100644
index 0000000..858f09b
--- /dev/null
+++ b/src/coverage.ts
@@ -0,0 +1,48 @@
+import type { CoverageResult, CoverageMapping } from "./types";
+
+export function coverage(
+  tests: string[],
+  requirements: string[],
+  options?: { threshold?: number }
+): CoverageResult {
+  const threshold = Math.max(0, Math.min(1, options?.threshold ?? 0.3));
+
+  if (!Array.isArray(tests) || !Array.isArray(requirements)) {
+    throw new TypeError("coverage() requires arrays of strings");
+  }
+
+  const mapping: CoverageMapping[] = requirements.map((req) => {
+    const matchedTests = tests
+      .map((test, idx) => ({ test, idx, sim: similarity(req, test) }))
+      .filter((m) => m.sim >= threshold)
+      .sort((a, b) => b.sim - a.sim)
+      .map((m) => m.test);
+    return { requirement: req, matchedTests, covered: matchedTests.length > 0 };
+  });
+
+  const covered = mapping.filter((m) => m.covered).map((m) => m.requirement);
+  const uncovered = mapping.filter((m) => !m.covered).map((m) => m.requirement);
+  const coveragePercent = requirements.length > 0
+    ? Math.round((covered.length / requirements.length) * 100)
+    : 100;
+
+  return { covered, uncovered, coveragePercent, mapping };
+}
+
+// Local Jaccard similarity (same algorithm as duplicates.ts but decoupled)
+function tokenize(text: string): Set<string> {
+  const STOP_WORDS = new Set(["a","an","the","is","are","was","were","be","been","being","have","has","had","do","does","did","will","would","could","should","may","might","shall","can","need","must","to","of","in","for","on","with","at","by","from","as","into","about","between","through","after","before","during","and","but","or","not","no","it","its","this","that","these","those","i","we","you","he","she","they","my","our","your"]);
+  return new Set(
+    text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((w) => w.length > 1 && !STOP_WORDS.has(w))
+  );
+}
+
+function similarity(a: string, b: string): number {
+  const setA = tokenize(a);
+  const setB = tokenize(b);
+  if (setA.size === 0 || setB.size === 0) return 0;
+  let intersection = 0;
+  for (const token of setA) if (setB.has(token)) intersection++;
+  const union = new Set([...setA, ...setB]).size;
+  return union > 0 ? intersection / union : 0;
+}
diff --git a/src/index.ts b/src/index.ts
index 1fc7565..7357d29 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -2,6 +2,8 @@ export { boundaries } from "./boundaries";
 export { flaky } from "./flaky";
 export { testEach } from "./test-each";
 export { detectDuplicates } from "./duplicates";
+export { coverage } from "./coverage";
+export { suggest } from "./suggest";
 
 export type {
   BoundaryResult,
@@ -18,4 +20,7 @@ export type {
   DuplicateOptions,
   TestEachOptions,
   TestEachRow,
+  CoverageResult,
+  CoverageMapping,
+  SuggestionResult,
 } from "./types";
diff --git a/src/suggest.ts b/src/suggest.ts
new file mode 100644
index 0000000..871a7b4
--- /dev/null
+++ b/src/suggest.ts
@@ -0,0 +1,52 @@
+import type { SuggestionResult } from "./types";
+
+const PATTERNS: { pattern: RegExp; category: string; suggestion: string }[] = [
+  { pattern: /^should\s+(create|add|save|insert|post|submit|register|sign.?up)/i, category: "negative", suggestion: "Consider negative case: what happens with invalid or missing input?" },
+  { pattern: /^should\s+(update|edit|modify|change|patch)/i, category: "negative", suggestion: "Consider negative case: what if the resource doesn't exist?" },
+  { pattern: /^should\s+(delete|remove|destroy)/i, category: "negative", suggestion: "Consider negative case: what if the resource is already deleted?" },
+  { pattern: /^should\s+(display|show|render|list|get|fetch|load|read)/i, category: "empty", suggestion: "Consider edge case: what if the result is empty or null?" },
+  { pattern: /^should\s+(search|filter|sort|find)/i, category: "boundary", suggestion: "Consider boundary: what about empty query, very long query, or special characters?" },
+  { pattern: /login|auth|sign.?in|session|token/i, category: "auth", suggestion: "Consider auth: what if the user is not authenticated or session expired?" },
+  { pattern: /upload|file|image|attachment|document/i, category: "file", suggestion: "Consider edge case: what about empty files, oversized files, or unsupported formats?" },
+  { pattern: /payment|checkout|order|cart|price|billing/i, category: "error", suggestion: "Consider error handling: what if payment fails or times out?" },
+  { pattern: /email|notification|sms|message/i, category: "async", suggestion: "Consider async: what if delivery fails or is delayed?" },
+  { pattern: /permission|role|access|admin/i, category: "auth", suggestion: "Consider authorization: what if user lacks required permissions?" },
+  { pattern: /pagination|page|scroll|infinite|load.?more/i, category: "boundary", suggestion: "Consider boundary: first page, last page, empty page, page beyond max." },
+  { pattern: /concurrent|parallel|simultaneous|race/i, category: "concurrency", suggestion: "Consider concurrency: what if two users perform the same action simultaneously?" },
+];
+
+// Generic suggestions when no specific patterns match
+const GENERIC: string[] = [
+  "Consider negative case: what happens when input is invalid?",
+  "Consider edge case: empty or null values.",
+  "Consider boundary values: min, max, zero, one.",
+  "Consider error handling: what if the operation fails?",
+];
+
+export function suggest(description: string): SuggestionResult {
+  if (typeof description !== "string" || description.trim().length === 0) {
+    return { suggestions: GENERIC, score: GENERIC.length };
+  }
+
+  const matched = new Map<string, string>();
+  for (const p of PATTERNS) {
+    if (p.pattern.test(description) && !matched.has(p.category)) {
+      matched.set(p.category, p.suggestion);
+    }
+  }
+
+  // Always check for missing common aspects
+  const lower = description.toLowerCase();
+  if (!lower.includes("error") && !lower.includes("fail") && !lower.includes("invalid") && !matched.has("negative")) {
+    matched.set("negative", "Consider negative case: what happens with invalid input?");
+  }
+  if (!lower.includes("empty") && !lower.includes("null") && !lower.includes("zero") && !lower.includes("none") && !matched.has("empty")) {
+    matched.set("empty", "Consider edge case: empty, null, or zero values.");
+  }
+  if (!lower.includes("boundary") && !lower.includes("limit") && !lower.includes("max") && !lower.includes("min") && !matched.has("boundary")) {
+    matched.set("boundary", "Consider boundary values for relevant fields.");
+  }
+
+  const suggestions = Array.from(matched.values());
+  return { suggestions, score: suggestions.length };
+}
diff --git a/src/types.ts b/src/types.ts
index eb40c24..0dec269 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -96,3 +96,23 @@ export interface TestEachOptions {
 
 /** A single test.each row: [label, input, expected]. */
 export type TestEachRow = [string, unknown, boolean];
+
+// Coverage
+export interface CoverageMapping {
+  requirement: string;
+  matchedTests: string[];
+  covered: boolean;
+}
+
+export interface CoverageResult {
+  covered: string[];
+  uncovered: string[];
+  coveragePercent: number;
+  mapping: CoverageMapping[];
+}
+
+// Suggestions
+export interface SuggestionResult {
+  suggestions: string[];
+  score: number;
+}