eslint-plugin-traceability 1.1.9 → 1.1.11

package/README.md

@@ -21,6 +21,11 @@ For detailed setup with ESLint v9, see user-docs/eslint-9-setup-guide.md.
 
 Add the plugin to your ESLint configuration and enable the rules.
 
+Additional ESLint v9 configuration guidance:
+
+- For detailed configuration examples, see [Common Configuration Patterns](user-docs/eslint-9-setup-guide.md#common-configuration-patterns) in the ESLint 9 Setup Guide.
+- For troubleshooting ESLint flat-config errors, see [Troubleshooting ESLint Configuration](user-docs/eslint-9-setup-guide.md#troubleshooting-eslint-configuration).
+
 Example eslint.config.js (ESLint v9 flat config):
 
 ```js

package/lib/src/rules/require-req-annotation.d.ts

@@ -2,6 +2,8 @@
  * Rule to enforce @req annotation on functions
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
+ * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  */
 declare const _default: any;
 export default _default;

package/lib/src/rules/require-req-annotation.js

@@ -4,6 +4,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Rule to enforce @req annotation on functions
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
+ * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  */
 exports.default = {
     meta: {
@@ -33,6 +35,48 @@ exports.default = {
                     });
                 }
             },
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-TYPESCRIPT-SUPPORT
+             */
+            TSDeclareFunction(node) {
+                const jsdoc = sourceCode.getJSDocComment(node);
+                const leading = node.leadingComments || [];
+                const comments = sourceCode.getCommentsBefore(node) || [];
+                const all = [...leading, ...comments];
+                const hasReq = (jsdoc && jsdoc.value.includes("@req")) ||
+                    all.some((c) => c.value.includes("@req"));
+                if (!hasReq) {
+                    context.report({
+                        node,
+                        messageId: "missingReq",
+                        fix(fixer) {
+                            return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
+                        },
+                    });
+                }
+            },
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-TYPESCRIPT-SUPPORT
+             */
+            TSMethodSignature(node) {
+                const jsdoc = sourceCode.getJSDocComment(node);
+                const leading = node.leadingComments || [];
+                const comments = sourceCode.getCommentsBefore(node) || [];
+                const all = [...leading, ...comments];
+                const hasReq = (jsdoc && jsdoc.value.includes("@req")) ||
+                    all.some((c) => c.value.includes("@req"));
+                if (!hasReq) {
+                    context.report({
+                        node,
+                        messageId: "missingReq",
+                        fix(fixer) {
+                            return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
+                        },
+                    });
+                }
+            },
         };
     },
 };

package/lib/src/rules/require-story-annotation.d.ts

@@ -5,6 +5,8 @@
  * @req REQ-OPTIONS-SCOPE - Support configuring which function types to enforce via options
  * @req REQ-EXPORT-PRIORITY - Add exportPriority option to target exported or non-exported
  * @req REQ-UNIFIED-CHECK - Implement unified checkNode for all supported node types
+ * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  */
 declare const _default: any;
 export default _default;

package/lib/src/rules/require-story-annotation.js

@@ -6,6 +6,8 @@
  * @req REQ-OPTIONS-SCOPE - Support configuring which function types to enforce via options
  * @req REQ-EXPORT-PRIORITY - Add exportPriority option to target exported or non-exported
  * @req REQ-UNIFIED-CHECK - Implement unified checkNode for all supported node types
+ * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
@@ -96,6 +98,12 @@ function resolveTargetNode(sourceCode, node) {
             }
         }
     }
+    else if (node.type === "TSMethodSignature") {
+        const exp = findAncestorNode(node, ["TSInterfaceDeclaration"]);
+        if (exp) {
+            target = exp;
+        }
+    }
     else if (node.type === "MethodDefinition") {
         target = node;
     }
@@ -124,6 +132,30 @@ function checkStoryAnnotation(sourceCode, context, node, scope, exportPriority)
     if (!shouldCheckNode(node, scope, exportPriority)) {
         return;
     }
+    // Special handling for TSMethodSignature: allow annotation on the method itself
+    if (node.type === "TSMethodSignature") {
+        // If annotated on the method signature, skip
+        if (hasStoryAnnotation(sourceCode, node)) {
+            return;
+        }
+        // Otherwise, check on interface declaration
+        const intf = resolveTargetNode(sourceCode, node);
+        if (hasStoryAnnotation(sourceCode, intf)) {
+            return;
+        }
+        // Missing annotation: report on the interface declaration
+        context.report({
+            node: intf,
+            messageId: "missingStory",
+            fix(fixer) {
+                const indentLevel = intf.loc.start.column;
+                const indent = " ".repeat(indentLevel);
+                const insertPos = intf.range[0] - indentLevel;
+                return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}/** @story <story-file>.story.md */\n`);
+            },
+        });
+        return;
+    }
     const target = resolveTargetNode(sourceCode, node);
     if (hasStoryAnnotation(sourceCode, target)) {
         return;
@@ -162,6 +194,8 @@ exports.default = {
                                 "FunctionExpression",
                                 "ArrowFunctionExpression",
                                 "MethodDefinition",
+                                "TSDeclareFunction",
+                                "TSMethodSignature",
                             ],
                         },
                         uniqueItems: true,
@@ -182,6 +216,8 @@ exports.default = {
             "FunctionExpression",
             "ArrowFunctionExpression",
             "MethodDefinition",
+            "TSDeclareFunction",
+            "TSMethodSignature",
         ];
         const exportPriority = options.exportPriority || "all";
         return {
@@ -197,6 +233,16 @@ exports.default = {
             MethodDefinition(node) {
                 checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
             },
+            // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+            // @req REQ-FUNCTION-DETECTION - Detect TS-specific function syntax
+            TSDeclareFunction(node) {
+                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+            },
+            // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+            // @req REQ-FUNCTION-DETECTION - Detect TS-specific function syntax
+            TSMethodSignature(node) {
+                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+            },
         };
     },
 };

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

@@ -10,7 +10,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const eslint_1 = require("eslint");
 const require_req_annotation_1 = __importDefault(require("../../src/rules/require-req-annotation"));
-const ruleTester = new eslint_1.RuleTester();
+const ruleTester = new eslint_1.RuleTester({
+    languageOptions: {
+        parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+    },
+});
 describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
     ruleTester.run("require-req-annotation", require_req_annotation_1.default, {
         valid: [
@@ -22,6 +26,22 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
                 name: "[REQ-ANNOTATION-REQUIRED] valid with @story and @req annotations",
                 code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-EXAMPLE\n */\nfunction bar() {}`,
             },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT] valid with @req annotation on TSDeclareFunction",
+                code: `/**\n * @req REQ-EXAMPLE\n */\ndeclare function foo(): void;`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT] valid with @req annotation on TSMethodSignature",
+                code: `interface I {\n  /**\n   * @req REQ-EXAMPLE\n   */\n  method(): void;\n}`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
         ],
         invalid: [
             {
@@ -36,6 +56,26 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
                 output: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\n/** @req <REQ-ID> */\nfunction qux() {}`,
                 errors: [{ messageId: "missingReq" }],
             },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSDeclareFunction",
+                code: `declare function baz(): void;`,
+                output: `/** @req <REQ-ID> */\ndeclare function baz(): void;`,
+                errors: [{ messageId: "missingReq" }],
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSMethodSignature",
+                code: `interface I { method(): void; }`,
+                output: `interface I { /** @req <REQ-ID> */\nmethod(): void; }`,
+                errors: [{ messageId: "missingReq" }],
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
         ],
     });
 });

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

@@ -40,6 +40,26 @@ const arrowFn = () => {};`,
                 name: "[REQ-ANNOTATION-REQUIRED] valid on class method with annotation",
                 code: `class A {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
             },
+            {
+                name: "[REQ-FUNCTION-DETECTION] valid with annotation on TS declare function",
+                code: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+declare function tsDecl(): void;`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+                },
+            },
+            {
+                name: "[REQ-FUNCTION-DETECTION] valid with annotation on TS method signature",
+                code: `interface C {
+  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+  method(): void;
+}`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+                },
+            },
         ],
         invalid: [
             {
@@ -66,6 +86,32 @@ const arrowFn = () => {};`,
                 output: `class C {\n  /** @story <story-file>.story.md */\n  method() {}\n}`,
                 errors: [{ messageId: "missingStory" }],
             },
+            {
+                name: "[REQ-ANNOTATION-REQUIRED] missing @story on TS declare function",
+                code: `declare function tsDecl(): void;`,
+                output: `/** @story <story-file>.story.md */
+declare function tsDecl(): void;`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+                },
+                errors: [{ messageId: "missingStory" }],
+            },
+            {
+                name: "[REQ-ANNOTATION-REQUIRED] missing @story on TS method signature",
+                code: `interface D {
+  method(): void;
+}`,
+                output: `/** @story <story-file>.story.md */
+interface D {
+  method(): void;
+}`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+                },
+                errors: [{ messageId: "missingStory" }],
+            },
         ],
     });
     ruleTester.run("require-story-annotation with exportPriority option", require_story_annotation_1.default, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.1.9",
+  "version": "1.1.11",
   "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",
@@ -17,7 +17,7 @@
     "build": "tsc -p tsconfig.json",
     "type-check": "tsc --noEmit -p tsconfig.json",
     "lint": "eslint \"src/**/*.{js,ts}\" \"tests/**/*.{js,ts}\" --max-warnings=0",
-    "test": "jest --ci --bail",
+    "test": "jest --ci --bail && node tests/integration/cli-integration.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "duplication": "jscpd src tests --reporters console --threshold 3",
@@ -75,6 +75,11 @@
     "node": ">=14"
   },
   "overrides": {
-    "glob": ">=11.0.4"
+    "glob": "12.0.0",
+    "http-cache-semantics": ">=4.1.1",
+    "ip": ">=2.0.2",
+    "semver": ">=7.5.2",
+    "socks": ">=2.7.2",
+    "tar": ">=6.1.12"
   }
 }