eslint-plugin-traceability 1.6.0 → 1.6.2

package/lib/src/utils/annotation-checker.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkReqAnnotation = checkReqAnnotation;
 const require_story_utils_1 = require("../rules/helpers/require-story-utils");
+const require_story_io_1 = require("../rules/helpers/require-story-io");
 /**
  * Helper to retrieve the JSDoc comment for a node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -42,17 +43,129 @@ function combineComments(leading, before) {
 function commentContainsReq(c) {
     return c && typeof c.value === "string" && c.value.includes("@req");
 }
+/**
+ * Line-based helper adapted from linesBeforeHasStory to detect @req.
+ */
+function linesBeforeHasReq(sourceCode, node) {
+    const lines = sourceCode && sourceCode.lines;
+    const startLine = node && node.loc && typeof node.loc.start?.line === "number"
+        ? node.loc.start.line
+        : null;
+    if (!Array.isArray(lines) || typeof startLine !== "number") {
+        return false;
+    }
+    const from = Math.max(0, startLine - 1 - require_story_io_1.LOOKBACK_LINES);
+    const to = Math.max(0, startLine - 1);
+    for (let i = from; i < to; i++) {
+        const text = lines[i];
+        if (typeof text === "string" && text.includes("@req")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parent-chain helper adapted from parentChainHasStory to detect @req.
+ */
+function parentChainHasReq(sourceCode, node) {
+    let p = node && node.parent;
+    while (p) {
+        const pComments = typeof sourceCode?.getCommentsBefore === "function"
+            ? sourceCode.getCommentsBefore(p) || []
+            : [];
+        if (Array.isArray(pComments) &&
+            pComments.some((c) => typeof c.value === "string" && c.value.includes("@req"))) {
+            return true;
+        }
+        const pLeading = p.leadingComments || [];
+        if (Array.isArray(pLeading) &&
+            pLeading.some((c) => typeof c.value === "string" && c.value.includes("@req"))) {
+            return true;
+        }
+        p = p.parent;
+    }
+    return false;
+}
+/**
+ * Fallback text window helper adapted from fallbackTextBeforeHasStory to detect @req.
+ */
+function fallbackTextBeforeHasReq(sourceCode, node) {
+    if (typeof sourceCode?.getText !== "function" ||
+        !Array.isArray((node && node.range) || [])) {
+        return false;
+    }
+    const range = node.range;
+    if (!Array.isArray(range) || typeof range[0] !== "number") {
+        return false;
+    }
+    try {
+        const start = Math.max(0, range[0] - require_story_io_1.FALLBACK_WINDOW);
+        const textBefore = sourceCode.getText().slice(start, range[0]);
+        if (typeof textBefore === "string" && textBefore.includes("@req")) {
+            return true;
+        }
+    }
+    catch {
+        /* noop */
+    }
+    return false;
+}
 /**
  * Helper to determine whether a JSDoc or any nearby comments contain a @req annotation.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
  */
-function hasReqAnnotation(jsdoc, comments) {
+function hasReqAnnotation(jsdoc, comments, context, node) {
+    try {
+        const sourceCode = context && typeof context.getSourceCode === "function"
+            ? context.getSourceCode()
+            : undefined;
+        if (sourceCode && node) {
+            if (linesBeforeHasReq(sourceCode, node) ||
+                parentChainHasReq(sourceCode, node) ||
+                fallbackTextBeforeHasReq(sourceCode, node)) {
+                return true;
+            }
+        }
+    }
+    catch {
+        // Swallow detection errors and fall through to simple checks.
+    }
+    // BRANCH @req detection on JSDoc or comments
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQ-DETECTION
     return ((jsdoc &&
         typeof jsdoc.value === "string" &&
         jsdoc.value.includes("@req")) ||
         comments.some(commentContainsReq));
 }
+/**
+ * Determine the most appropriate node to attach an inserted JSDoc to.
+ * Prefers outer function-like constructs such as methods, variable declarators,
+ * or wrapping expression statements for function expressions.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
+ */
+function getFixTargetNode(node) {
+    const parent = node && node.parent;
+    if (!parent) {
+        return node;
+    }
+    // If the node is part of a class/obj method definition, attach to the MethodDefinition
+    if (parent.type === "MethodDefinition") {
+        return parent;
+    }
+    // If the node is the init of a variable declarator, attach to the VariableDeclarator
+    if (parent.type === "VariableDeclarator" && parent.init === node) {
+        return parent;
+    }
+    // If the parent is an expression statement (e.g. IIFE or assigned via expression),
+    // attach to the outer ExpressionStatement.
+    if (parent.type === "ExpressionStatement") {
+        return parent;
+    }
+    return node;
+}
 /**
  * Creates a fix function that inserts a missing @req JSDoc before the node.
  * Returned function is a proper named function so no inline arrow is used.
@@ -60,8 +173,9 @@ function hasReqAnnotation(jsdoc, comments) {
  * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
  */
 function createMissingReqFix(node) {
+    const target = getFixTargetNode(node);
     return function missingReqFix(fixer) {
-        return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
+        return fixer.insertTextBefore(target, "/** @req <REQ-ID> */\n");
     };
 }
 /**
@@ -72,30 +186,49 @@ function createMissingReqFix(node) {
  * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
  * @req REQ-ERROR-SPECIFIC - Provide specific error details including node name
  * @req REQ-ERROR-LOCATION - Include contextual location information in errors
+ * @req REQ-ERROR-SUGGESTION - Provide actionable suggestions or fixes where possible
+ * @req REQ-ERROR-CONTEXT - Include contextual hints to help understand the error
  */
-function reportMissing(context, node) {
-    const rawName = (0, require_story_utils_1.getNodeName)(node);
+function reportMissing(context, node, enableFix = true) {
+    const rawName = (0, require_story_utils_1.getNodeName)(node) ?? (node && (0, require_story_utils_1.getNodeName)(node.parent));
     const name = rawName ?? "(anonymous)";
-    context.report({
-        node,
+    const nameNode = (node && node.id && node.id.type === "Identifier"
+        ? node.id
+        : node && node.key && node.key.type === "Identifier"
+            ? node.key
+            : node) ?? node;
+    const reportOptions = {
+        node: nameNode,
         messageId: "missingReq",
-        data: { name },
-        fix: createMissingReqFix(node),
-    });
+        data: { name, functionName: name },
+    };
+    if (enableFix) {
+        reportOptions.fix = createMissingReqFix(node);
+    }
+    context.report(reportOptions);
 }
 /**
  * Helper to check @req annotation presence on TS declare functions and method signatures.
+ * This helper is intentionally scope/exportPriority agnostic and focuses solely
+ * on detection and reporting of @req annotations for the given node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+ * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
+ * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
  */
-function checkReqAnnotation(context, node) {
+function checkReqAnnotation(context, node, options) {
+    const { enableFix = true } = options ?? {};
     const sourceCode = context.getSourceCode();
     const jsdoc = getJsdocComment(sourceCode, node);
     const leading = getLeadingComments(node);
     const comments = getCommentsBefore(sourceCode, node);
     const all = combineComments(leading, comments);
-    const hasReq = hasReqAnnotation(jsdoc, all);
+    const hasReq = hasReqAnnotation(jsdoc, all, context, node);
+    // BRANCH when a @req annotation is missing and must be reported
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQ-DETECTION
+    // @req REQ-ANNOTATION-REPORTING
     if (!hasReq) {
-        reportMissing(context, node);
+        reportMissing(context, node, enableFix);
     }
 }

package/lib/tests/cli-error-handling.test.js

@@ -39,6 +39,6 @@ describe("CLI Error Handling for Traceability Plugin (Story 001.0-DEV-PLUGIN-SET
         });
         // Expect non-zero exit and missing annotation message on stdout
         expect(result.status).not.toBe(0);
-        expect(result.stdout).toContain("Missing @story annotation");
+        expect(result.stdout).toContain("Function 'foo' must have an explicit @story annotation. Add a JSDoc or line comment with @story that points to the implementing story file (for example, docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md)");
     });
 });

package/lib/tests/plugin-default-export-and-configs.test.js

@@ -36,7 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-PLUGIN-STRUCTURE - Validate plugin default export and configs in src/index.ts
+ * @req REQ-ERROR-SEVERITY - Validate error severity configuration in plugin configs
  */
 const index_1 = __importStar(require("../src/index"));
 describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", () => {
@@ -69,4 +71,18 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
         const strictRules = index_1.configs.strict[0].rules;
         expect(strictRules).toEqual(index_1.configs.recommended[0].rules);
     });
+    it("[REQ-ERROR-SEVERITY] configs.recommended maps valid-annotation-format to warn and others to error", () => {
+        const recommendedRules = index_1.configs.recommended[0].rules;
+        expect(recommendedRules).toHaveProperty("traceability/valid-annotation-format", "warn");
+        expect(recommendedRules).toHaveProperty("traceability/require-story-annotation", "error");
+        expect(recommendedRules).toHaveProperty("traceability/require-req-annotation", "error");
+        expect(recommendedRules).toHaveProperty("traceability/require-branch-annotation", "error");
+        expect(recommendedRules).toHaveProperty("traceability/valid-story-reference", "error");
+        expect(recommendedRules).toHaveProperty("traceability/valid-req-reference", "error");
+    });
+    it("[REQ-ERROR-SEVERITY] configs.strict uses same severity mapping as recommended", () => {
+        const strictRules = index_1.configs.strict[0].rules;
+        const recommendedRules = index_1.configs.recommended[0].rules;
+        expect(strictRules).toEqual(recommendedRules);
+    });
 });

package/lib/tests/rules/auto-fix-behavior-008.test.js

@@ -28,6 +28,10 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                     name: "[REQ-AUTOFIX-MISSING] already annotated function is unchanged",
                     code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction alreadyAnnotated() {}`,
                 },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] already annotated class method is unchanged",
+                    code: `class A {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                },
             ],
             invalid: [
                 {
@@ -46,6 +50,78 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                         },
                     ],
                 },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before function expression when missing",
+                    code: `const fnExpr = function() {};`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'fnExpr', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before class method when missing",
+                    code: `class C {\n  method() {}\n}`,
+                    output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before TS declare function when missing",
+                    code: `declare function tsDecl(): void;`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
+                    languageOptions: {
+                        parser: require("@typescript-eslint/parser"),
+                        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+                    },
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'tsDecl', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before TS method signature when missing",
+                    code: `interface D {\n  method(): void;\n}`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
+                    languageOptions: {
+                        parser: require("@typescript-eslint/parser"),
+                        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+                    },
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
             ],
         });
     });

package/lib/tests/rules/error-reporting.test.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-ERROR-SPECIFIC - Specific details about what annotation is missing or invalid
  * @req REQ-ERROR-SUGGESTION - Suggest concrete steps to fix the issue
  * @req REQ-ERROR-CONTEXT - Include relevant context in error messages
+ * @req REQ-ERROR-LOCATION - Include precise location information in error messages
  */
 const eslint_1 = require("eslint");
 const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
@@ -18,31 +19,79 @@ const ruleTester = new eslint_1.RuleTester({
     },
 });
 describe("Error Reporting Enhancements for require-story-annotation (Story 007.0-DEV-ERROR-REPORTING)", () => {
-    ruleTester.run("require-story-annotation", require_story_annotation_1.default, {
-        valid: [
-            {
-                name: "[007.0-DEV-ERROR-REPORTING] valid with existing annotation",
-                code: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */ function foo() {}`,
-            },
-        ],
-        invalid: [
-            {
-                name: "[REQ-ERROR-SPECIFIC] missing @story annotation should report specific details and suggestion",
-                code: `function bar() {}`,
-                output: "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}",
-                errors: [
+    describe("valid cases", () => {
+        ruleTester.run("require-story-annotation", require_story_annotation_1.default, {
+            valid: [
+                {
+                    name: "[007.0-DEV-ERROR-REPORTING] valid with existing annotation",
+                    code: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */ function foo() {}`,
+                },
+            ],
+            invalid: [],
+        });
+    });
+    describe("REQ-ERROR-SPECIFIC - missing @story annotation should report specific details and suggestion", () => {
+        it("reports specific message, data, and suggestions for function 'bar'", () => {
+            const code = "function bar() {}";
+            const reported = [];
+            const context = {
+                id: "require-story-annotation",
+                options: [],
+                report: (descriptor) => {
+                    reported.push(descriptor);
+                },
+                getFilename: () => "test.js",
+                getSourceCode: () => ({
+                    text: code,
+                    getText: () => code,
+                    ast: {
+                        type: "Program",
+                        body: [],
+                        sourceType: "module",
+                    },
+                }),
+            };
+            const listeners = require_story_annotation_1.default.create(context);
+            // Minimal synthetic AST nodes for the visitors
+            const programNode = {
+                type: "Program",
+                body: [
                     {
-                        messageId: "missingStory",
-                        data: { name: "bar" },
-                        suggestions: [
-                            {
-                                desc: "Add JSDoc @story annotation for function 'bar', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
-                                output: "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}",
-                            },
-                        ],
+                        type: "FunctionDeclaration",
+                        id: { type: "Identifier", name: "bar" },
+                        params: [],
+                        body: {
+                            type: "BlockStatement",
+                            body: [],
+                        },
                     },
                 ],
-            },
-        ],
+                sourceType: "module",
+            };
+            const functionNode = programNode.body[0];
+            // Invoke visitors if they exist
+            if (typeof listeners.Program === "function") {
+                listeners.Program(programNode);
+            }
+            if (typeof listeners.FunctionDeclaration === "function") {
+                listeners.FunctionDeclaration(functionNode);
+            }
+            expect(reported.length).toBe(1);
+            const error = reported[0];
+            // Message template should be defined and contain the {{name}} placeholder
+            const template = require_story_annotation_1.default.meta?.messages?.missingStory;
+            expect(typeof template).toBe("string");
+            expect(template.length).toBeGreaterThan(0);
+            expect(template.includes("{{name}}")).toBe(true);
+            // Ensure messageId and data wiring is correct
+            expect(error.messageId).toBe("missingStory");
+            expect(error.data).toEqual({ name: "bar", functionName: "bar" });
+            // Suggestions
+            expect(Array.isArray(error.suggest)).toBe(true);
+            expect(error.suggest.length).toBeGreaterThanOrEqual(1);
+            const suggestion = error.suggest[0];
+            expect(suggestion.desc).toBe("Add JSDoc @story annotation for function 'bar', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */");
+            expect(suggestion.fix).toBeDefined();
+        });
     });
 });

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

@@ -4,9 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md, docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-BRANCH-DETECTION - Verify require-branch-annotation rule enforces branch annotations
+ * @req REQ-ERROR-SPECIFIC - Branch-level missing-annotation error messages are specific and informative
+ * @req REQ-ERROR-CONSISTENCY - Branch-level missing-annotation error messages follow shared conventions
+ * @req REQ-ERROR-SUGGESTION - Branch-level missing-annotation errors include suggestions when applicable
  */
 const eslint_1 = require("eslint");
 const require_branch_annotation_1 = __importDefault(require("../../src/rules/require-branch-annotation"));