eslint-plugin-traceability 1.14.0 → 1.14.1

package/lib/tests/rules/require-branch-annotation.test.js

@@ -23,12 +23,14 @@ const require_branch_annotation_1 = __importDefault(require("../../src/rules/req
 const ruleTester = new eslint_1.RuleTester({
     languageOptions: { parserOptions: { ecmaVersion: 2020 } },
 });
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 const makeMissingAnnotationErrors = (...missing) => missing.map((item) => ({
     messageId: "missingAnnotation",
     data: { missing: item },
 }));
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 const runRule = (tests) => ruleTester.run("require-branch-annotation", require_branch_annotation_1.default, tests);
-describe("Require Branch Annotation Rule (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
+describe("Require Branch Annotation Rule (Story 004.0-DEV-BRANCH-ANNOTATIONS)" /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */, () => {
     runRule({
         valid: [
             {
@@ -60,8 +62,22 @@ for (let i = 0; i < 10; i++) {}`,
   // @req REQ-BRANCH-DETECTION
   case 'a':
     break;
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-SWITCH-DEFAULT-REQUIRED
   default:
     break;
+}`,
+            },
+            {
+                name: "[REQ-SWITCH-FALLTHROUGH] valid fall-through group only requires annotation on last case before body",
+                code: `switch (status) {
+  case "pending":
+  case "processing":
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-SWITCH-FALLTHROUGH
+  case "validating":
+    handleInProgress();
+    break;
 }`,
             },
             {
@@ -101,6 +117,14 @@ do {
 /* @req REQ-BRANCH-DETECTION */
 for (const item of items) {
   process(item);
+}`,
+            },
+            {
+                name: "[REQ-LOOP-PLACEMENT-FLEXIBLE] for-of loop annotated via comment inside body",
+                code: `for (const item of items) {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-LOOP-ANNOTATION
+  process(item);
 }`,
             },
             {
@@ -117,6 +141,14 @@ for (const key in object) {
 /* @req REQ-BRANCH-DETECTION */
 while (condition) {
   iterate();
+}`,
+            },
+            {
+                name: "[REQ-LOOP-PLACEMENT-FLEXIBLE] while loop annotated via comment inside body",
+                code: `while (condition) {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-LOOP-ANNOTATION
+  iterate();
 }`,
             },
             {
@@ -138,13 +170,6 @@ if (outer) {
   if (inner) {
     doWork();
   }
-}`,
-            },
-            {
-                name: "[REQ-BRANCH-DETECTION] valid default case without annotations",
-                code: `switch (value) {
-  default:
-    doSomething();
 }`,
             },
             {
@@ -214,6 +239,17 @@ while (true) {}`,
 while (true) {}`,
                 errors: makeMissingAnnotationErrors("@story"),
             },
+            {
+                name: "[REQ-LOOP-ANNOTATION] missing annotations when loop body contains only non-comment code",
+                code: `for (const item of items) {
+  process(item);
+}`,
+                output: `// @story <story-file>.story.md
+for (const item of items) {
+  process(item);
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
             {
                 name: "[REQ-BRANCH-DETECTION] missing annotations on switch-case",
                 code: `switch (value) {
@@ -224,6 +260,50 @@ while (true) {}`,
   // @story <story-file>.story.md
   case 'a':
     break;
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
+            {
+                name: "[REQ-SWITCH-FALLTHROUGH] intermediate fall-through case should not be the only annotated case",
+                code: `switch (status) {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-SWITCH-FALLTHROUGH
+  case "pending":
+  case "processing":
+  case "validating":
+    handleInProgress();
+    break;
+}`,
+                output: `switch (status) {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-SWITCH-FALLTHROUGH
+  case "pending":
+  case "processing":
+  // @story <story-file>.story.md
+  case "validating":
+    handleInProgress();
+    break;
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
+            {
+                name: "[REQ-SWITCH-DEFAULT-REQUIRED] missing annotations on default case",
+                code: `switch (value) {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-BRANCH-DETECTION
+  case 'a':
+    doSomething();
+  default:
+    doDefault();
+}`,
+                output: `switch (value) {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-BRANCH-DETECTION
+  case 'a':
+    doSomething();
+  // @story <story-file>.story.md
+  default:
+    doDefault();
 }`,
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
@@ -238,17 +318,6 @@ do {
 } while (condition);`,
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
-            {
-                name: "[REQ-BRANCH-DETECTION] missing annotations on for-of loop",
-                code: `for (const item of items) {
-  process(item);
-}`,
-                output: `// @story <story-file>.story.md
-for (const item of items) {
-  process(item);
-}`,
-                errors: makeMissingAnnotationErrors("@story", "@req"),
-            },
             {
                 name: "[REQ-BRANCH-DETECTION] missing annotations on for-in loop",
                 code: `for (const key in object) {

package/lib/tests/rules/require-story-annotation.test.js

@@ -16,7 +16,7 @@ const ts_language_options_1 = require("../utils/ts-language-options");
 const ruleTester = new eslint_1.RuleTester({
     languageOptions: ts_language_options_1.tsRuleTesterLanguageOptions,
 });
-describe("Require Story Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
+describe("Require Story Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)" /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */ /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */, () => {
     ruleTester.run("require-story-annotation", require_story_annotation_1.default, {
         valid: [
             {
@@ -58,8 +58,12 @@ declare function tsDecl(): void;`,
 }`,
             }),
             {
-                name: "[REQ-ANNOTATION-REQUIRED] unannotated arrow function allowed by default",
-                code: `const arrowFn = () => {};`,
+                name: "[REQ-ARROW-FUNCTION-EXCLUDED] anonymous arrow callback in higher-order function is allowed without annotation",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction mapValues(items) {\n  return items.map(() => {\n    return 1;\n  });\n}`,
+            },
+            {
+                name: "[REQ-NESTED-FUNCTION-INHERITANCE] anonymous inner function inherits outer annotation",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction outer() {\n  const inner = function() {\n    return 1;\n  };\n  return inner();\n}`,
             },
         ],
         invalid: [
@@ -145,6 +149,38 @@ declare function tsDecl(): void;`,
                     },
                 ],
             }),
+            {
+                name: "[REQ-ARROW-FUNCTION-EXCLUDED] named arrow function must be annotated",
+                code: `const handler = () => {};`,
+                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst handler = () => {};`,
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'handler', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst handler = () => {};`,
+                            },
+                        ],
+                    },
+                ],
+            },
+            {
+                name: "[REQ-NESTED-FUNCTION-INHERITANCE] named inner function inside annotated outer must still be annotated",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction outer() {\n  function innerNamed() {\n    return 1;\n  }\n  return innerNamed();\n}`,
+                output: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction outer() {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction innerNamed() {\n    return 1;\n  }\n  return innerNamed();\n}`,
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'innerNamed', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction outer() {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction innerNamed() {\n    return 1;\n  }\n  return innerNamed();\n}`,
+                            },
+                        ],
+                    },
+                ],
+            },
         ],
     });
     ruleTester.run("require-story-annotation with exportPriority option", require_story_annotation_1.default, {
@@ -159,11 +195,6 @@ declare function tsDecl(): void;`,
                 code: `// @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\nexport function exportedAnnotated() {}`,
                 options: [{ exportPriority: "exported" }],
             },
-            {
-                name: "[exportPriority] exported arrow function missing @story annotation",
-                code: `export const arrowExported = () => {};`,
-                options: [{ exportPriority: "exported" }],
-            },
         ],
         invalid: [
             {
@@ -183,6 +214,23 @@ declare function tsDecl(): void;`,
                     },
                 ],
             },
+            {
+                name: "[exportPriority][REQ-ARROW-FUNCTION-EXCLUDED] exported named arrow function must be annotated",
+                code: `export const arrowExported = () => {};`,
+                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nexport const arrowExported = () => {};`,
+                options: [{ exportPriority: "exported" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'arrowExported', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nexport const arrowExported = () => {};`,
+                            },
+                        ],
+                    },
+                ],
+            },
         ],
     });
     ruleTester.run("require-story-annotation with scope option", require_story_annotation_1.default, {

package/lib/tests/utils/temp-dir-helpers.d.ts

@@ -1,7 +1,10 @@
 export interface TempDirHandle {
     /** The absolute path to the created temporary directory. */
     readonly dir: string;
-    /** Remove the directory recursively; safe to call multiple times. */
+    /**
+     * Remove the directory recursively; safe to call multiple times.
+     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
+     */
     cleanup(): void;
 }
 /**
@@ -10,5 +13,7 @@ export interface TempDirHandle {
  * This helper centralizes the mkdtemp + rmSync pattern that appears in
  * multiple maintenance tests so those tests can focus on behavior instead
  * of filesystem plumbing.
+ *
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-TEMP-HELPERS REQ-MAINT-SAFE
  */
 export declare function createTempDir(prefix: string): TempDirHandle;

package/lib/tests/utils/temp-dir-helpers.js

@@ -48,13 +48,14 @@ const path = __importStar(require("path"));
  * This helper centralizes the mkdtemp + rmSync pattern that appears in
  * multiple maintenance tests so those tests can focus on behavior instead
  * of filesystem plumbing.
+ *
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-TEMP-HELPERS REQ-MAINT-SAFE
  */
 function createTempDir(prefix) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
     return {
         dir,
         cleanup() {
-            // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
             fs.rmSync(dir, { recursive: true, force: true });
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",