feat: add description and explanation to each smell

Jhonatanmizu · Jhonatanmizu · commit bf6ff5f91ea7 · 2026-03-30T14:22:44.000-03:00
diff --git a/lib/core/detector-runner.test.ts b/lib/core/detector-runner.test.ts
@@ -51,13 +51,17 @@ describe("DetectorRunner", () => {
       end: { line: 1, column: 5 },
       message: "Smell 1",
       codeBlock: "const",
+      description: "Mock Smell 1",
+      explanation: "Explanation for mock smell 1.",
     };
     const mockSmell2: Smell = {
       file: mockFilePath,
       start: { line: 2, column: 0 },
       end: { line: 2, column: 5 },
       message: "Smell 2",
       codeBlock: "a = 1",
+      description: "Mock Smell 2",
+      explanation: "Explanation for mock smell 2.",
     };
 
     const mockDetector1: Detector = {
diff --git a/lib/core/detector.interface.ts b/lib/core/detector.interface.ts
@@ -12,6 +12,8 @@ export interface Smell {
   };
   message: string;
   codeBlock: string;
+  description: string;
+  explanation: string;
 }
 
 export interface Detector {
diff --git a/lib/core/watcher.test.ts b/lib/core/watcher.test.ts
@@ -168,6 +168,8 @@ describe("Watcher", () => {
       end: { line: 1, column: 10 },
       message: "Smell detected",
       codeBlock: "if (true) {}",
+      description: "Mock Smell",
+      explanation: "Explanation for mock smell.",
     };
     const mockRun = jest.fn<() => Promise<Smell[]>>().mockResolvedValue([mockSmell]);
     (DetectorRunner as jest.Mock).mockImplementation(() => ({
diff --git a/lib/detectors/anonymousTestLogic.ts b/lib/detectors/anonymousTestLogic.ts
@@ -4,6 +4,7 @@ import { Detector, Smell } from "@/core/detector.interface";
 import astService from "@/ast/ast.service";
 import { logger } from "@/shared/logger";
 import { jestTestAliases } from "@/shared/aliases";
+import { SMELL_DESCRIPTIONS } from "@/shared/smell-descriptions";
 
 const MINIMUM_WORDS_THRESHOLD = 2;
 
@@ -40,6 +41,8 @@ export class AnonymousTestLogicDetector implements Detector {
             end: { line: endLine, column: loc?.end.column ?? 0 },
             message: `Anonymous test case detected.`,
             codeBlock,
+            description: SMELL_DESCRIPTIONS.AnonymousTest.description,
+            explanation: SMELL_DESCRIPTIONS.AnonymousTest.explanation,
           });
         }
       }
diff --git a/lib/detectors/commentsOnlyTestLogic.ts b/lib/detectors/commentsOnlyTestLogic.ts
@@ -4,6 +4,7 @@ import { Detector, Smell } from "@/core/detector.interface";
 import astService from "@/ast/ast.service";
 import { logger } from "@/shared/logger";
 import { jestTestAliases } from "@/shared/aliases";
+import { SMELL_DESCRIPTIONS } from "@/shared/smell-descriptions";
 
 export class CommentsOnlyLogicTestDetector implements Detector {
   /**
@@ -36,6 +37,8 @@ export class CommentsOnlyLogicTestDetector implements Detector {
               end: { line: endLine, column: loc?.end.column ?? 0 },
               message: `Test case with only comments or empty body detected.`,
               codeBlock,
+              description: SMELL_DESCRIPTIONS.CommentsOnlyTest.description,
+              explanation: SMELL_DESCRIPTIONS.CommentsOnlyTest.explanation,
             });
           }
         }
diff --git a/lib/detectors/complexSnapshotTestLogic.ts b/lib/detectors/complexSnapshotTestLogic.ts
@@ -3,6 +3,7 @@ import * as t from "@babel/types";
 import { Detector, Smell } from "@/core/detector.interface";
 import astService from "@/ast/ast.service";
 import { logger } from "@/shared/logger";
+import { SMELL_DESCRIPTIONS } from "@/shared/smell-descriptions";
 
 const MAX_LINES_IN_SNAPSHOT = 50;
 
@@ -31,6 +32,8 @@ function buildSmell(
     message: `Complex ${kind} snapshot detected: snapshot exceeds ${MAX_LINES_IN_SNAPSHOT} lines. Consider simplifying the tested output or breaking it into smaller assertions.`,
     codeBlock:
       sourceCode.slice(node.start ?? 0, node.end ?? 0) || "// Unable to extract code snippet",
+    description: SMELL_DESCRIPTIONS.ComplexSnapshotTest.description,
+    explanation: SMELL_DESCRIPTIONS.ComplexSnapshotTest.explanation,
   };
 }
 
diff --git a/lib/detectors/conditionalTestLogic.ts b/lib/detectors/conditionalTestLogic.ts
@@ -4,6 +4,7 @@ import { Detector, Smell } from "@/core/detector.interface";
 import astService from "@/ast/ast.service";
 import { logger } from "@/shared/logger";
 import { jestTestAliases } from "@/shared/aliases";
+import { SMELL_DESCRIPTIONS } from "@/shared/smell-descriptions";
 
 export class ConditionalTestLogicDetector implements Detector {
   /**
@@ -36,6 +37,8 @@ export class ConditionalTestLogicDetector implements Detector {
           end: { line: endLine, column: loc?.end.column ?? 0 },
           message: `Conditional logic inside test case detected: ${node.type}`,
           codeBlock,
+          description: SMELL_DESCRIPTIONS.ConditionalTestLogic.description,
+          explanation: SMELL_DESCRIPTIONS.ConditionalTestLogic.explanation,
         });
       }
     } catch (err) {
diff --git a/lib/detectors/generalFixtureTestLogic.ts b/lib/detectors/generalFixtureTestLogic.ts
@@ -3,6 +3,7 @@ import * as t from "@babel/types";
 import astService from "@/ast/ast.service";
 import { Detector, Smell } from "@/core/detector.interface";
 import { logger } from "@/shared/logger";
+import { SMELL_DESCRIPTIONS } from "@/shared/smell-descriptions";
 
 interface SetupVariableOccurrence {
   startLine: number;
@@ -64,6 +65,8 @@ export class GeneralFixtureTestLogicDetector implements Detector {
             end: { line: occurrence.endLine, column: occurrence.endColumn },
             message: `General fixture detected: setup variable "${variableName}" is never used in test cases.`,
             codeBlock,
+            description: SMELL_DESCRIPTIONS.GeneralFixture.description,
+            explanation: SMELL_DESCRIPTIONS.GeneralFixture.explanation,
           });
         }
       }
diff --git a/lib/detectors/identicalDescriptionTestLogic.ts b/lib/detectors/identicalDescriptionTestLogic.ts
@@ -4,6 +4,7 @@ import { Detector, Smell } from "@/core/detector.interface";
 import { logger } from "@/shared/logger";
 import { jestTestAliases } from "@/shared/aliases";
 import astService from "@/ast/ast.service";
+import { SMELL_DESCRIPTIONS } from "@/shared/smell-descriptions";
 
 export class IdenticalDescriptionTestLogicDetector implements Detector {
   async detect(ast: t.File, sourceCode: string, file: string): Promise<Smell[]> {
@@ -34,6 +35,8 @@ export class IdenticalDescriptionTestLogicDetector implements Detector {
               end: { line: endLine, column: loc?.end.column ?? 0 },
               message: `Identical Description test case detected.`,
               codeBlock,
+              description: SMELL_DESCRIPTIONS.IdenticalDescription.description,
+              explanation: SMELL_DESCRIPTIONS.IdenticalDescription.explanation,
             });
           }
           testDescriptionSet.add(testDescription);
diff --git a/lib/detectors/overcommentedTestLogic.ts b/lib/detectors/overcommentedTestLogic.ts
@@ -3,6 +3,7 @@ import * as t from "@babel/types";
 import { Detector, Smell } from "@/core/detector.interface";
 import astService from "@/ast/ast.service";
 import { MAX_COMMENTS_PER_TEST } from "@/shared/constants";
+import { SMELL_DESCRIPTIONS } from "@/shared/smell-descriptions";
 import { jestTestAliases } from "@/shared/aliases";
 
 export class OvercommentedTestLogicDetector implements Detector {
@@ -31,6 +32,8 @@ export class OvercommentedTestLogicDetector implements Detector {
           codeBlock:
             sourceCode.substring(testStatement.start!, testStatement.end!) ||
             "// Unable to extract code snippet",
+          description: SMELL_DESCRIPTIONS.OvercommentedTest.description,
+          explanation: SMELL_DESCRIPTIONS.OvercommentedTest.explanation,
         });
       }
     }
diff --git a/lib/detectors/testWithoutDescriptionLogic.ts b/lib/detectors/testWithoutDescriptionLogic.ts
@@ -4,6 +4,7 @@ import astService from "@/ast/ast.service";
 import { Detector, Smell } from "@/core/detector.interface";
 import { jestTestAliases } from "@/shared/aliases";
 import { logger } from "@/shared/logger";
+import { SMELL_DESCRIPTIONS } from "@/shared/smell-descriptions";
 
 const TEST_CALL_SELECTOR = `CallExpression[callee.name=/${jestTestAliases.join("|")}/]`;
 
@@ -67,6 +68,8 @@ export class DetectorTestWithoutDescriptionLogic implements Detector {
           start: { line: loc?.start.line ?? 0, column: loc?.start.column ?? 0 },
           end: { line: loc?.end.line ?? 0, column: loc?.end.column ?? 0 },
           codeBlock,
+          description: SMELL_DESCRIPTIONS.TestWithoutDescription.description,
+          explanation: SMELL_DESCRIPTIONS.TestWithoutDescription.explanation,
         });
       }
     } catch (err) {
diff --git a/lib/shared/smell-descriptions.ts b/lib/shared/smell-descriptions.ts
@@ -0,0 +1,54 @@
+export interface SmellDescription {
+  description: string;
+  explanation: string;
+}
+
+export const SMELL_DESCRIPTIONS = {
+  AnonymousTest: {
+    description: "Anonymous Test",
+    explanation:
+      "A test case with a very short or vague description (two words or fewer) makes it difficult to understand what behavior is being verified. Tests should have meaningful names that clearly express the intent, the scenario, and the expected outcome.",
+  },
+
+  CommentsOnlyTest: {
+    description: "Comments-Only Test",
+    explanation:
+      "A test case whose body is empty or contains only comments provides no real verification. These tests always pass regardless of the code under test, creating a false sense of coverage and hiding untested behavior.",
+  },
+
+  ComplexSnapshotTest: {
+    description: "Complex Snapshot",
+    explanation:
+      "A snapshot test that spans too many lines is difficult to review, understand, and maintain. When such a snapshot breaks, it is hard to identify what actually changed. Consider asserting only the relevant parts of the output or breaking the test into smaller, focused assertions.",
+  },
+
+  ConditionalTestLogic: {
+    description: "Conditional Test Logic",
+    explanation:
+      "Conditional statements (if/switch) inside a test case introduce branching paths that make the test harder to read and reason about. A single test should verify one clear scenario; branches often indicate that multiple test cases should be written instead, one for each code path.",
+  },
+
+  GeneralFixture: {
+    description: "General Fixture",
+    explanation:
+      "A variable defined in a setup hook (beforeAll/beforeEach) that is never referenced in any test case adds unnecessary complexity to the test suite. This usually means the fixture is outdated, was set up speculatively, or belongs to a different test group. Remove or scope it appropriately.",
+  },
+
+  IdenticalDescription: {
+    description: "Identical Description",
+    explanation:
+      "Multiple test cases sharing the same description make it impossible to distinguish between them when a test fails. Each test case must have a unique name that precisely identifies the specific scenario and expected outcome being verified.",
+  },
+
+  OvercommentedTest: {
+    description: "Overcommented Test",
+    explanation:
+      "A test case with an excessive number of comments often signals that the test logic is too complex or poorly structured. Well-written tests should be self-explanatory through clear naming and simple assertions. Relying heavily on comments to explain what a test does is a sign it should be refactored.",
+  },
+
+  TestWithoutDescription: {
+    description: "Test Without Description",
+    explanation:
+      "A test case with no description at all makes it completely impossible to understand its purpose from the test report. Every test must have a descriptive name that communicates what behavior is being tested, under what conditions, and what the expected result is.",
+  },
+} as const satisfies Record<string, SmellDescription>;

Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,8 @@ export interface Smell {`
`12`	`12`	`};`
`13`	`13`	`message: string;`
`14`	`14`	`codeBlock: string;`
	`15`	`+ description: string;`
	`16`	`+ explanation: string;`
`15`	`17`	`}`
`16`	`18`
`17`	`19`	`export interface Detector {`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@ import { Detector, Smell } from "@/core/detector.interface";`
`4`	`4`	`import astService from "@/ast/ast.service";`
`5`	`5`	`import { logger } from "@/shared/logger";`
`6`	`6`	`import { jestTestAliases } from "@/shared/aliases";`
	`7`	`+import { SMELL_DESCRIPTIONS } from "@/shared/smell-descriptions";`
`7`	`8`
`8`	`9`	`const MINIMUM_WORDS_THRESHOLD = 2;`
`9`	`10`
`@@ -40,6 +41,8 @@ export class AnonymousTestLogicDetector implements Detector {`
`40`	`41`	`end: { line: endLine, column: loc?.end.column ?? 0 },`
`41`	`42`	message: `Anonymous test case detected.`,
`42`	`43`	`codeBlock,`
	`44`	`+ description: SMELL_DESCRIPTIONS.AnonymousTest.description,`
	`45`	`+ explanation: SMELL_DESCRIPTIONS.AnonymousTest.explanation,`
`43`	`46`	`});`
`44`	`47`	`}`
`45`	`48`	`}`