eslint-plugin-traceability 1.6.0 → 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.d.ts

@@ -1,7 +1,12 @@
-/**
+/****
+ * Rule to enforce @req annotation on functions
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-RULE-EXPORT - Export the rule object for ESLint
  * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
+ * @req REQ-FUNCTION-DETECTION - Detect function declarations, function expressions, and method definitions (including TypeScript declarations)
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of which exports are checked
+ * @req REQ-EXPORT-PRIORITY - Allow configuration of export priority behavior
  */
-declare const _default: any;
-export default _default;
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -1,37 +1,71 @@
 "use strict";
 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
- */
+const require_story_helpers_1 = require("./helpers/require-story-helpers");
 const annotation_checker_1 = require("../utils/annotation-checker");
-/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-RULE-EXPORT - Export the rule object for ESLint
- * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
- */
-exports.default = {
+const rule = {
     meta: {
         type: "problem",
         fixable: "code",
         docs: {
-            description: "Require @req annotations on functions",
+            description: "Require @req annotations on function-like exports (declarations, expressions, and methods, excluding arrow functions)",
             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: [],
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    scope: {
+                        type: "array",
+                        items: {
+                            enum: require_story_helpers_1.DEFAULT_SCOPE,
+                        },
+                        uniqueItems: true,
+                    },
+                    exportPriority: {
+                        enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
     /**
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
      * @req REQ-CREATE-HOOK - Provide create(context) hook for rule behavior
-     * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
+     * @req REQ-FUNCTION-DETECTION - Detect function declarations, function expressions, and method definitions (including TS-specific nodes)
+     * @req REQ-CONFIGURABLE-SCOPE - Respect configurable scope of which exports are checked
+     * @req REQ-EXPORT-PRIORITY - Respect configurable export priority when determining which nodes to check
      */
     create(context) {
+        const options = context.options?.[0] ?? {};
+        const rawScope = options?.scope;
+        const scope = Array.isArray(rawScope) && rawScope.length > 0 ? rawScope : require_story_helpers_1.DEFAULT_SCOPE;
+        const exportPriority = options?.exportPriority ?? "all";
+        const shouldCheck = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority);
+        /**
+         * Helper to conditionally run the annotation check only when the node
+         * should be processed according to scope/exportPriority.
+         */
+        const runCheck = (node) => {
+            if (!shouldCheck(node))
+                return;
+            (0, annotation_checker_1.checkReqAnnotation)(context, node, { enableFix: false });
+        };
         return {
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -39,18 +73,44 @@ exports.default = {
              * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on function declarations
              */
             FunctionDeclaration(node) {
-                return (0, annotation_checker_1.checkReqAnnotation)(context, node);
+                runCheck(node);
+            },
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-FUNCTION-DETECTION - Detect function expressions
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on function expressions
+             */
+            FunctionExpression(node) {
+                if (node.parent && node.parent.type === "MethodDefinition") {
+                    return;
+                }
+                runCheck(node);
             },
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+             * @req REQ-FUNCTION-DETECTION - Detect method definitions
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on method definitions
              */
-            TSDeclareFunction: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
+            MethodDefinition(node) {
+                runCheck(node);
+            },
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript declare functions
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on TS declare functions
              */
-            TSMethodSignature: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
+            TSDeclareFunction(node) {
+                runCheck(node);
+            },
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript method signatures
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on TS method signatures
+             */
+            TSMethodSignature(node) {
+                runCheck(node);
+            },
         };
     },
 };
+exports.default = rule;

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

@@ -7,14 +7,22 @@
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-AUTOFIX-MISSING - This rule supports auto-fixing missing @story annotations per Story 008.0 auto-fix behavior.
+ * @req REQ-AUTOFIX-SAFE - Auto-fix behavior only inserts @story annotation JSDoc comments and never changes executable or runtime code.
+ * @req REQ-AUTOFIX-PRESERVE - Auto-fix inserts a minimal placeholder JSDoc in a way that preserves existing surrounding formatting and structure.
  */
 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,20 +6,34 @@ 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: {
         type: "problem",
         docs: {
-            description: "Require @story annotations on functions",
+            description: "Require @story annotations on functions and auto-fix missing annotations where possible",
             recommended: "error",
         },
         hasSuggestions: true,
+        /**
+         * Auto-fix support for inserting @story annotations.
+         *
+         * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+         * @req REQ-ANNOTATION-REQUIRED
+         * @req REQ-AUTOFIX-MISSING - `fixable: \"code\"` is used to implement REQ-AUTOFIX-MISSING for missing @story annotations.
+         * @req REQ-AUTOFIX-SAFE - Auto-fix is conservative and only adds a single-line JSDoc @story annotation without modifying existing runtime expressions.
+         * @req REQ-AUTOFIX-PRESERVE - Auto-fix behavior preserves surrounding code formatting and indentation when inserting the placeholder JSDoc.
+         */
         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: [
             {
@@ -42,6 +56,7 @@ const rule = {
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
      * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
      * @req REQ-CREATE-HOOK
+     * @req REQ-AUTOFIX-MISSING - The create hook wires in visitors that are capable of providing auto-fix suggestions for missing @story annotations.
      */
     create(context) {
         const sourceCode = context.getSourceCode();

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

@@ -8,6 +8,7 @@ const STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-PRESERVE - Avoid risky text replacements when the annotation tag cannot be located
  */
 const TAG_NOT_FOUND_INDEX = -1;
 /**
@@ -89,6 +90,8 @@ function buildReqErrorMessage(kind, value) {
  *
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
+ * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
  */
 function getFixedStoryPath(original) {
     if (original.includes("..")) {
@@ -124,10 +127,18 @@ function reportInvalidStoryFormat(context, comment, collapsed) {
  * for common path suffix issues by locating and replacing the path text
  * within the original comment.
  *
+ * This helper:
+ *   - only adjusts the story path suffix when a safe, well-understood
+ *     transformation is available, satisfying REQ-AUTOFIX-SAFE.
+ *   - preserves all surrounding comment formatting, spacing, and text
+ *     outside the path substring, satisfying REQ-AUTOFIX-PRESERVE.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and avoid changing semantics
+ * @req REQ-AUTOFIX-PRESERVE - Auto-fix must preserve surrounding formatting and comments
  */
 function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
     const sourceCode = context.getSourceCode();
@@ -313,10 +324,31 @@ 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: [],
+        /**
+         * This rule's fixable support is limited to safe @story path suffix normalization per Story 008.0.
+         * Fixes are limited strictly to adjusting the suffix portion of the @story path (e.g., adding
+         * `.md` or `.story.md`), preserving all other comment text and whitespace exactly as written.
+         *
+         * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+         * @req REQ-AUTOFIX-SAFE
+         * @req REQ-AUTOFIX-PRESERVE
+         */
         fixable: "code",
     },
     /**

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.d.ts

@@ -1,6 +1,12 @@
 /**
  * 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
  */
-export declare function checkReqAnnotation(context: any, node: any): void;
+export declare function checkReqAnnotation(context: any, node: any, options?: {
+    enableFix?: boolean;
+}): void;