eslint-plugin-traceability 1.6.1 → 1.6.2

package/lib/src/index.d.ts

@@ -12,6 +12,12 @@ import type { Rule } from "eslint";
 declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference"];
 type RuleName = (typeof RULE_NAMES)[number];
 declare const rules: Record<RuleName, Rule.RuleModule>;
+/**
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SEVERITY - Map rule types to appropriate ESLint severity levels (errors vs warnings)
+ * The recommended and strict configs treat missing annotations and missing references as errors,
+ * while formatting issues are reported as warnings, matching the story's severity conventions.
+ */
 declare const configs: {
     recommended: {
         plugins: {

package/lib/src/index.js

@@ -67,6 +67,12 @@ RULE_NAMES.forEach(
         };
     }
 });
+/**
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SEVERITY - Map rule types to appropriate ESLint severity levels (errors vs warnings)
+ * The recommended and strict configs treat missing annotations and missing references as errors,
+ * while formatting issues are reported as warnings, matching the story's severity conventions.
+ */
 const configs = {
     recommended: [
         {

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

@@ -100,9 +100,11 @@ declare function shouldProcessNode(node: any, scope: string[], exportPriority?:
  * Report a missing @story annotation for a function-like node
  * Provides a suggestion to add the annotation.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing annotations with suggestion
  * @req REQ-AUTOFIX-MISSING - Provide autofix for missing annotations while preserving suggestions
+ * @req REQ-ERROR-SPECIFIC - Error reports must include both name and functionName in the data payload for specific function context
  * @param {Rule.RuleContext} context - ESLint rule context used to report
  * @param {any} sourceCode - ESLint sourceCode object
  * @param {any} node - AST node that is missing the annotation
@@ -112,10 +114,15 @@ declare function reportMissing(context: Rule.RuleContext, sourceCode: any, node:
 /**
  * Report a missing @story annotation for a method-like node
  * Provides a suggestion to update the method/interface with the annotation.
+ * The error data payload uses both name and functionName for consistent, specific error context.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing method/interface annotations with suggestion
  * @req REQ-AUTOFIX-MISSING - Provide autofix for missing method/interface annotations while preserving suggestions
+ * @req REQ-ERROR-SPECIFIC - Method error reports must include both name and functionName in the data payload for specific function context
+ * @req REQ-ERROR-LOCATION - Method error reports must use the method name node to anchor error location
+ * @req REQ-ERROR-CONTEXT - Method error reports must include functionName data for consistent error context
  * @param {Rule.RuleContext} context - ESLint rule context to report
  * @param {any} sourceCode - ESLint sourceCode object
  * @param {any} node - AST node that is missing the annotation

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

@@ -238,9 +238,11 @@ function shouldProcessNode(node, scope, exportPriority = "all") {
  * Report a missing @story annotation for a function-like node
  * Provides a suggestion to add the annotation.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing annotations with suggestion
  * @req REQ-AUTOFIX-MISSING - Provide autofix for missing annotations while preserving suggestions
+ * @req REQ-ERROR-SPECIFIC - Error reports must include both name and functionName in the data payload for specific function context
  * @param {Rule.RuleContext} context - ESLint rule context used to report
  * @param {any} sourceCode - ESLint sourceCode object
  * @param {any} node - AST node that is missing the annotation
@@ -260,7 +262,7 @@ function reportMissing(context, sourceCode, node, passedTarget) {
         context.report({
             node: nameNode,
             messageId: "missingStory",
-            data: { name },
+            data: { name, functionName: name },
             fix: (0, require_story_core_1.createAddStoryFix)(resolvedTarget),
             suggest: [
                 {
@@ -277,10 +279,15 @@ function reportMissing(context, sourceCode, node, passedTarget) {
 /**
  * Report a missing @story annotation for a method-like node
  * Provides a suggestion to update the method/interface with the annotation.
+ * The error data payload uses both name and functionName for consistent, specific error context.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing method/interface annotations with suggestion
  * @req REQ-AUTOFIX-MISSING - Provide autofix for missing method/interface annotations while preserving suggestions
+ * @req REQ-ERROR-SPECIFIC - Method error reports must include both name and functionName in the data payload for specific function context
+ * @req REQ-ERROR-LOCATION - Method error reports must use the method name node to anchor error location
+ * @req REQ-ERROR-CONTEXT - Method error reports must include functionName data for consistent error context
  * @param {Rule.RuleContext} context - ESLint rule context to report
  * @param {any} sourceCode - ESLint sourceCode object
  * @param {any} node - AST node that is missing the annotation
@@ -297,7 +304,7 @@ function reportMethod(context, sourceCode, node, passedTarget) {
         context.report({
             node: nameNode,
             messageId: "missingStory",
-            data: { name },
+            data: { name, functionName: name },
             fix: (0, require_story_core_1.createMethodFix)(resolvedTarget),
             suggest: [
                 {

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

@@ -16,7 +16,11 @@ const rule = {
         },
         fixable: "code",
         messages: {
-            missingAnnotation: "Missing {{missing}} annotation on code branch",
+            /**
+             * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+             * @req REQ-ERROR-CONSISTENCY - Use shared branch error message convention with {{missing}} placeholder
+             */
+            missingAnnotation: "Branch is missing required annotation: {{missing}}.",
         },
         schema: [
             {

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

@@ -11,7 +11,19 @@ const rule = {
             recommended: "error",
         },
         messages: {
-            missingReq: "Missing @req annotation for function '{{name}}' (REQ-ANNOTATION-REQUIRED)",
+            /**
+             * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+             * @req REQ-ERROR-CONSISTENCY - Align missing @req function error with cross-rule conventions
+             * @req REQ-ERROR-SPECIFIC - Provide specific function name in error message
+             * @req REQ-ERROR-SUGGESTION - Suggest adding a @req annotation with an example identifier
+             * @req REQ-ERROR-CONTEXT - Include @req format guidance in the error text
+             * @req REQ-ERROR-LOCATION - Report the error at the function identifier location
+             * @req REQ-ERROR-SEVERITY - Use ESLint severity level "error" for missing @req annotations
+             *
+             * This rule uses ESLint's message data placeholders for the function name,
+             * specifically the {{name}} placeholder populated via context.report.
+             */
+            missingReq: "Function '{{functionName}}' is missing a required @req annotation. Add a JSDoc or line comment with @req (for example, '@req REQ-EXAMPLE') referencing the appropriate requirement from the story file.",
         },
         schema: [
             {

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

@@ -16,9 +16,13 @@ import type { Rule } from "eslint";
  * ESLint rule to require @story annotations on functions/methods.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED
  * @req REQ-AUTOFIX-MISSING - This rule participates in auto-fix for missing @story annotations.
+ * @req REQ-ERROR-MSG-CONTENT - Error message instructs adding an explicit @story annotation that points to the implementing story file.
+ * @req REQ-ERROR-MSG-PLACEHOLDER - Error message retains the {{name}} placeholder while also providing functionName in the data payload for cross-rule consistency.
+ * @req REQ-ERROR-MSG-ACTIONABLE - Error message text is concise, imperative, and describes the required remediation.
  */
 declare const rule: Rule.RuleModule;
 export default rule;

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

@@ -6,9 +6,13 @@ const require_story_helpers_1 = require("./helpers/require-story-helpers");
  * ESLint rule to require @story annotations on functions/methods.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED
  * @req REQ-AUTOFIX-MISSING - This rule participates in auto-fix for missing @story annotations.
+ * @req REQ-ERROR-MSG-CONTENT - Error message instructs adding an explicit @story annotation that points to the implementing story file.
+ * @req REQ-ERROR-MSG-PLACEHOLDER - Error message retains the {{name}} placeholder while also providing functionName in the data payload for cross-rule consistency.
+ * @req REQ-ERROR-MSG-ACTIONABLE - Error message text is concise, imperative, and describes the required remediation.
  */
 const rule = {
     meta: {
@@ -29,7 +33,7 @@ const rule = {
          */
         fixable: "code",
         messages: {
-            missingStory: "Missing @story annotation for function '{{name}}' (REQ-ANNOTATION-REQUIRED)",
+            missingStory: "Function '{{name}}' 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).",
         },
         schema: [
             {

package/lib/src/rules/valid-annotation-format.js

@@ -324,8 +324,20 @@ exports.default = {
             recommended: "error",
         },
         messages: {
-            invalidStoryFormat: "{{details}}",
-            invalidReqFormat: "{{details}}",
+            /**
+             * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+             * @req REQ-ERROR-SPECIFIC - Provide specific details about invalid @story annotation format
+             * @req REQ-ERROR-CONTEXT - Include human-readable details about the expected @story annotation format
+             * @req REQ-ERROR-CONSISTENCY - Use shared "Invalid annotation format: {{details}}." message pattern across rules
+             */
+            invalidStoryFormat: "Invalid annotation format: {{details}}.",
+            /**
+             * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+             * @req REQ-ERROR-SPECIFIC - Provide specific details about invalid @req annotation format
+             * @req REQ-ERROR-CONTEXT - Include human-readable details about the expected @req annotation format
+             * @req REQ-ERROR-CONSISTENCY - Use shared "Invalid annotation format: {{details}}." message pattern across rules
+             */
+            invalidReqFormat: "Invalid annotation format: {{details}}.",
         },
         schema: [],
         /**

package/lib/src/rules/valid-req-reference.js

@@ -170,7 +170,21 @@ exports.default = {
             recommended: "error",
         },
         messages: {
+            /**
+             * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+             * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+             * @req REQ-ERROR-SPECIFIC - Provide specific diagnostics when a referenced requirement ID cannot be found in a story
+             * @req REQ-ERROR-CONTEXT - Include both the missing requirement ID and the story path in the message
+             * @req REQ-ERROR-CONSISTENCY - Use a consistent message template for requirement lookup failures
+             */
             reqMissing: "Requirement '{{reqId}}' not found in '{{storyPath}}'",
+            /**
+             * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+             * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+             * @req REQ-ERROR-SPECIFIC - Indicate that the story path associated with a @req annotation is invalid
+             * @req REQ-ERROR-CONTEXT - Include the problematic storyPath value so the developer can correct it
+             * @req REQ-ERROR-CONSISTENCY - Reuse the same storyPath placeholder convention used by other rules
+             */
             invalidPath: "Invalid story path '{{storyPath}}'",
         },
         schema: [],

package/lib/src/rules/valid-story-reference.js

@@ -180,8 +180,29 @@ exports.default = {
             recommended: "error",
         },
         messages: {
+            /**
+             * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+             * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+             * @req REQ-ERROR-SPECIFIC - Provide specific diagnostics when a referenced story file cannot be found
+             * @req REQ-ERROR-CONTEXT - Include the original story path in the error message for troubleshooting
+             * @req REQ-ERROR-CONSISTENCY - Use consistent file-related error wording and placeholders across rules
+             */
             fileMissing: "Story file '{{path}}' not found",
+            /**
+             * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+             * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+             * @req REQ-ERROR-SPECIFIC - Indicate that the story file extension is invalid and what is expected
+             * @req REQ-ERROR-CONTEXT - Include the provided path so developers can see which reference is wrong
+             * @req REQ-ERROR-CONSISTENCY - Reuse the same pattern of "{{path}}" placeholder across file validation messages
+             */
             invalidExtension: "Invalid story file extension for '{{path}}', expected '.story.md'",
+            /**
+             * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+             * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+             * @req REQ-ERROR-SPECIFIC - Explain that the story path is invalid due to absolute or unsafe traversal
+             * @req REQ-ERROR-CONTEXT - Surface the offending path to assist with correcting the reference
+             * @req REQ-ERROR-CONSISTENCY - Maintain a consistent template for invalid path diagnostics across rules
+             */
             invalidPath: "Invalid story path '{{path}}'",
             /**
              * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md

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,12 +43,94 @@ 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
@@ -103,14 +186,21 @@ 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, enableFix = true) {
     const rawName = (0, require_story_utils_1.getNodeName)(node) ?? (node && (0, require_story_utils_1.getNodeName)(node.parent));
     const name = rawName ?? "(anonymous)";
+    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,
+        node: nameNode,
         messageId: "missingReq",
-        data: { name },
+        data: { name, functionName: name },
     };
     if (enableFix) {
         reportOptions.fix = createMissingReqFix(node);
@@ -133,7 +223,7 @@ function checkReqAnnotation(context, node, options) {
     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

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/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"));

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

@@ -108,17 +108,32 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @req on function without JSDoc",
                 code: `function baz() {}`,
-                errors: [{ messageId: "missingReq", data: { name: "baz" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "baz", functionName: "baz" },
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @req on function with only @story annotation",
                 code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction qux() {}`,
-                errors: [{ messageId: "missingReq", data: { name: "qux" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "qux", functionName: "qux" },
+                    },
+                ],
             },
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSDeclareFunction",
                 code: `declare function baz(): void;`,
-                errors: [{ messageId: "missingReq", data: { name: "baz" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "baz", functionName: "baz" },
+                    },
+                ],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
@@ -127,7 +142,12 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSMethodSignature",
                 code: `interface I { method(): void; }`,
-                errors: [{ messageId: "missingReq", data: { name: "method" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "method", functionName: "method" },
+                    },
+                ],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
@@ -136,27 +156,52 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
             {
                 name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on FunctionExpression assigned to variable",
                 code: `const fn = function () {};`,
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
             },
             {
                 name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on anonymous FunctionExpression (no variable name)",
                 code: `(function () {})();`,
-                errors: [{ messageId: "missingReq", data: { name: "(anonymous)" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "(anonymous)", functionName: "(anonymous)" },
+                    },
+                ],
             },
             {
                 name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on MethodDefinition in class",
                 code: `class C {\n  m() {}\n}`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "m", functionName: "m" },
+                    },
+                ],
             },
             {
                 name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on MethodDefinition in object literal",
                 code: `const o = { m() {} };`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "m", functionName: "m" },
+                    },
+                ],
             },
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT][REQ-FUNCTION-DETECTION][Story 003.0] missing @req on TS FunctionExpression in variable declarator",
                 code: `const fn = function () {};`,
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
@@ -165,7 +210,12 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT][REQ-FUNCTION-DETECTION][Story 003.0] missing @req on exported TS FunctionExpression in variable declarator",
                 code: `export const fn = function () {};`,
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
@@ -175,43 +225,78 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
                 name: "[REQ-CONFIGURABLE-SCOPE][Story 003.0] FunctionDeclaration still reported when scope only includes FunctionDeclaration",
                 code: `function scoped() {}`,
                 options: [{ scope: ["FunctionDeclaration"] }],
-                errors: [{ messageId: "missingReq", data: { name: "scoped" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "scoped", functionName: "scoped" },
+                    },
+                ],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported function reported when exportPriority is 'exported'",
                 code: `export function exportedFn() {}`,
                 options: [{ exportPriority: "exported" }],
-                errors: [{ messageId: "missingReq", data: { name: "exportedFn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "exportedFn", functionName: "exportedFn" },
+                    },
+                ],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported function reported when exportPriority is 'non-exported'",
                 code: `function nonExported() {}`,
                 options: [{ exportPriority: "non-exported" }],
-                errors: [{ messageId: "missingReq", data: { name: "nonExported" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "nonExported", functionName: "nonExported" },
+                    },
+                ],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported method reported when exportPriority is 'exported'",
                 code: `export class C {\n  m() {}\n}`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "m", functionName: "m" },
+                    },
+                ],
                 options: [{ exportPriority: "exported" }],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported method reported when exportPriority is 'non-exported'",
                 code: `class C {\n  m() {}\n}`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "m", functionName: "m" },
+                    },
+                ],
                 options: [{ exportPriority: "non-exported" }],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported FunctionExpression reported when exportPriority is 'exported'",
                 code: `export const fn = function () {};`,
                 options: [{ exportPriority: "exported" }],
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported FunctionExpression reported when exportPriority is 'non-exported'",
                 code: `const fn = function () {};`,
                 options: [{ exportPriority: "non-exported" }],
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
             },
         ],
     });

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

@@ -105,6 +105,7 @@ declare function tsDecl(): void;`,
                 errors: [
                     {
                         messageId: "missingStory",
+                        data: { name: "method", functionName: "method" },
                         suggestions: [
                             {
                                 desc: `Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,

package/lib/tests/rules/valid-annotation-format.test.js

@@ -7,6 +7,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @req REQ-FORMAT-SPECIFICATION - Verify valid-annotation-format rule enforces annotation format syntax
+ * Tests for: docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-MESSAGES-CONSISTENT - Verify invalid annotation errors use consistent wording and structure
+ * @req REQ-ERROR-MESSAGES-ACTIONABLE - Verify invalid annotation errors provide actionable guidance and examples
+ * @req REQ-ERROR-MESSAGES-IDENTIFIERS - Verify invalid annotation errors echo the offending identifier/path in the message
  */
 const eslint_1 = require("eslint");
 const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));

package/lib/tests/rules/valid-req-reference.test.js

@@ -7,6 +7,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
  * @req REQ-DEEP-PARSE - Verify valid-req-reference rule enforces existing requirement content
+ *
+ * Additional coverage for error reporting behavior:
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SPECIFIC - Verify requirement-level errors identify the exact missing requirement
+ * @req REQ-ERROR-CONTEXT - Verify requirement-level errors include relevant story path context
+ * @req REQ-ERROR-CONSISTENCY - Verify requirement-level error messages are consistent across cases
  */
 const eslint_1 = require("eslint");
 const valid_req_reference_1 = __importDefault(require("../../src/rules/valid-req-reference"));

package/lib/tests/rules/valid-story-reference.test.js

@@ -7,6 +7,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-FILE-EXISTENCE - Verify valid-story-reference rule enforces existing .story.md files
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SPECIFIC - Verify file-related error messages are specific about failure causes
+ * @req REQ-ERROR-CONTEXT - Verify file-related error messages include contextual information (path, underlying error)
+ * @req REQ-ERROR-CONSISTENCY - Verify file-related error messages follow consistent formatting and identifiers
+ * @req REQ-ERROR-HANDLING - Verify file-related errors are reported via diagnostics instead of uncaught exceptions
  */
 const eslint_1 = require("eslint");
 const valid_story_reference_1 = __importDefault(require("../../src/rules/valid-story-reference"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "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",