eslint-plugin-traceability 1.1.10 → 1.2.0

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/tests/integration/cli-integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/integration/cli-integration.test.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for CLI integration functionality
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Validate plugin registers via CLI
+ */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+describe("[docs/stories/001.0-DEV-PLUGIN-SETUP.story.md] CLI Integration (traceability plugin)", () => {
+    const eslintPkgDir = path_1.default.dirname(require.resolve("eslint/package.json"));
+    const eslintCliPath = path_1.default.join(eslintPkgDir, "bin", "eslint.js");
+    const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
+    const tests = [
+        {
+            name: "reports error when @story annotation is missing",
+            code: "function foo() {}",
+            rule: "traceability/require-story-annotation:error",
+            expectedStatus: 1,
+        },
+        {
+            name: "does not report error when @story annotation is present",
+            code: `/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ */
+function foo() {}`,
+            rule: "traceability/require-story-annotation:error",
+            expectedStatus: 0,
+        },
+        {
+            name: "reports error when @req annotation is missing",
+            code: "function bar() {}",
+            rule: "traceability/require-req-annotation:error",
+            expectedStatus: 1,
+        },
+        {
+            name: "reports error when @story annotation uses path traversal and @req annotation uses path traversal",
+            code: `/**
+ * @story ../docs/stories/invalid.story.md
+ * @req ../docs/requirements/REQ-INVALID.md
+ */
+function bar() {}`,
+            rule: "traceability/valid-req-reference:error",
+            expectedStatus: 1,
+        },
+        {
+            name: "reports error when @story annotation uses absolute path and @req annotation uses absolute path",
+            code: `/**
+ * @story /absolute/path/to/story.story.md
+ * @req /etc/passwd
+ */
+function baz() {}`,
+            rule: "traceability/valid-req-reference:error",
+            expectedStatus: 1,
+        },
+    ];
+    function runEslint(code, rule) {
+        const args = [
+            "--no-config-lookup",
+            "--config",
+            configPath,
+            "--stdin",
+            "--stdin-filename",
+            "foo.js",
+            "--rule",
+            "no-unused-vars:off",
+            "--rule",
+            rule,
+        ];
+        const result = (0, child_process_1.spawnSync)(process.execPath, [eslintCliPath, ...args], {
+            encoding: "utf-8",
+            input: code,
+        });
+        return result;
+    }
+    tests.forEach((testCase) => {
+        it(`[REQ-PLUGIN-STRUCTURE] ${testCase.name}`, () => {
+            const result = runEslint(testCase.code, testCase.rule);
+            expect(result.status).toBe(testCase.expectedStatus);
+        });
+    });
+});

package/lib/tests/maintenance/detect.test.js

@@ -24,4 +24,22 @@ describe("detectStaleAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
             fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
         }
     });
+    it("[REQ-MAINT-DETECT] should detect stale annotation references", () => {
+        const tmpDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "detect-stale-"));
+        try {
+            const filePath = path_1.default.join(tmpDir, "file.ts");
+            const storyName = "stale.story.md";
+            const content = `
+/**
+ * @story ${storyName}
+ */`;
+            fs_1.default.writeFileSync(filePath, content, "utf8");
+            const result = (0, detect_1.detectStaleAnnotations)(tmpDir);
+            expect(result).toHaveLength(1);
+            expect(result).toContain(storyName);
+        }
+        finally {
+            fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
 });

package/lib/tests/maintenance/update-isolated.test.js

@@ -63,4 +63,8 @@ function foo() {}
             fs.rmSync(tmpDir, { recursive: true, force: true });
         }
     });
+    it("[REQ-MAINT-UPDATE] should return 0 when directory does not exist", () => {
+        const count = (0, update_1.updateAnnotationReferences)("non-existent-dir", "old.md", "new.md");
+        expect(count).toBe(0);
+    });
 });

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.1.10",
+  "version": "1.2.0",
   "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",
@@ -13,7 +13,6 @@
     "doc": "docs"
   },
   "scripts": {
-    "prelint": "npm run build",
     "build": "tsc -p tsconfig.json",
     "type-check": "tsc --noEmit -p tsconfig.json",
     "lint": "eslint \"src/**/*.{js,ts}\" \"tests/**/*.{js,ts}\" --max-warnings=0",
@@ -60,7 +59,7 @@
     "actionlint": "^2.0.6",
     "eslint": "^9.39.1",
     "husky": "^9.1.7",
-    "jest": "^29.7.0",
+    "jest": "^30.2.0",
     "jscpd": "^4.0.5",
     "lint-staged": "^16.2.6",
     "prettier": "^3.6.2",