eslint-plugin-traceability 1.11.1 → 1.11.3

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

@@ -1,348 +1,6 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-env node */
-/**
- * Rule to validate @req annotation references refer to existing requirements in story files
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Parse comments and extract story/requirement metadata
- * @req REQ-DEEP-MATCH - Match @req annotations to story file requirements
- * @req REQ-DEEP-CACHE - Cache requirement IDs per story file for efficient validation
- * @req REQ-DEEP-PATH - Validate and resolve story file paths safely
- */
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-/**
- * Token index configuration for @supports annotations.
- * This clarifies the expected positions of the story path and first requirement ID
- * and avoids hard-coded "magic number" indices in parsing logic.
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- */
-const IMPLEMENTS_TOKENS = {
-    STORY_INDEX: 1,
-    FIRST_REQ_INDEX: 2,
-};
-/**
- * Extract the story path from a JSDoc comment.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Parse JSDoc comment lines to locate @story annotations
- */
-function extractStoryPath(comment) {
-    const rawLines = comment.value.split(/\r?\n/);
-    for (const rawLine of rawLines) {
-        const line = rawLine.trim().replace(/^\*+\s*/, "");
-        if (line.startsWith("@story")) {
-            const parts = line.split(/\s+/);
-            return parts[1] || null;
-        }
-    }
-    return null;
-}
-/**
- * Validate and resolve the referenced story path.
- * Performs traversal/absolute checks and resolves to a disk path.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PATH - Validate and resolve referenced story file paths
- */
-function validateAndResolveStoryPath(opts) {
-    const { comment, context, storyPath, cwd } = opts;
-    if (storyPath.includes("..") || path_1.default.isAbsolute(storyPath)) {
-        context.report({
-            node: comment,
-            messageId: "invalidPath",
-            data: { storyPath },
-        });
-        return null;
-    }
-    const resolvedStoryPath = path_1.default.resolve(cwd, storyPath);
-    if (!resolvedStoryPath.startsWith(cwd + path_1.default.sep) &&
-        resolvedStoryPath !== cwd) {
-        context.report({
-            node: comment,
-            messageId: "invalidPath",
-            data: { storyPath },
-        });
-        return null;
-    }
-    return resolvedStoryPath;
-}
-/**
- * Load and cache requirement IDs from a story file.
- * Reads the story file, extracts requirement IDs, and updates the cache.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-CACHE - Cache requirement IDs discovered in story files
- * @req REQ-DEEP-PARSE - Parse story file contents to extract requirement identifiers
- */
-function loadAndCacheRequirements(opts) {
-    const { resolvedStoryPath, reqCache } = opts;
-    if (!reqCache.has(resolvedStoryPath)) {
-        try {
-            const content = fs_1.default.readFileSync(resolvedStoryPath, "utf8");
-            const found = new Set();
-            const regex = /REQ-[A-Z0-9-]+/g;
-            let match;
-            while ((match = regex.exec(content)) !== null) {
-                found.add(match[0]);
-            }
-            reqCache.set(resolvedStoryPath, found);
-        }
-        catch {
-            reqCache.set(resolvedStoryPath, new Set());
-        }
-    }
-    return reqCache.get(resolvedStoryPath);
-}
-/**
- * Perform the final requirement existence check and report if missing.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-MATCH - Verify that a referenced requirement ID exists in the story
- */
-function checkRequirementExists(opts) {
-    const { comment, context, reqId, storyPath, reqSet } = opts;
-    if (!reqSet.has(reqId)) {
-        context.report({
-            node: comment,
-            messageId: "reqMissing",
-            data: { reqId, storyPath },
-        });
-    }
-}
-/**
- * Extract requirement ID from a @req line.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Parse annotation lines to extract requirement IDs
- */
-function extractReqIdFromLine(line) {
-    const parts = line.split(/\s+/);
-    return parts[1];
-}
-/**
- * Resolve story path and load requirements set for validation.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PATH - Validate and resolve referenced story file paths
- * @req REQ-DEEP-CACHE - Cache requirement IDs discovered in story files
- */
-function resolveStoryAndRequirements(opts) {
-    const { comment, context, storyPath, cwd, reqCache } = opts;
-    const resolvedStoryPath = validateAndResolveStoryPath({
-        comment,
-        context,
-        storyPath,
-        cwd,
-    });
-    if (!resolvedStoryPath) {
-        return { resolvedStoryPath: null, reqSet: null };
-    }
-    const reqSet = loadAndCacheRequirements({
-        resolvedStoryPath,
-        reqCache,
-    });
-    return { resolvedStoryPath, reqSet };
-}
-/**
- * Validate a @req annotation line against the extracted story content.
- * Performs path validation, file reading, caching, and requirement existence checks.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PATH - Validate and resolve referenced story file paths
- * @req REQ-DEEP-CACHE - Cache requirement IDs discovered in story files
- * @req REQ-DEEP-MATCH - Verify that a referenced requirement ID exists in the story
- * @req REQ-DEEP-PARSE - Parse story file contents to extract requirement identifiers
- */
-function validateReqLine(opts) {
-    const { comment, context, line, storyPath, cwd, reqCache } = opts;
-    const reqId = extractReqIdFromLine(line);
-    if (!reqId || !storyPath) {
-        return;
-    }
-    const { reqSet } = resolveStoryAndRequirements({
-        comment,
-        context,
-        storyPath,
-        cwd,
-        reqCache,
-    });
-    if (!reqSet) {
-        return;
-    }
-    checkRequirementExists({
-        comment,
-        context,
-        reqId,
-        storyPath,
-        reqSet,
-    });
-}
-/**
- * Parse a @supports annotation line into its story path and requirement IDs.
- * Expects the format: "@supports <storyPath> <REQ-ID-1> <REQ-ID-2> ..."
- * Invalid formats (missing storyPath or reqIds) are ignored by this deep rule.
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-VALIDATE - Support validation of @supports annotations
- * @req REQ-MIXED-SUPPORT - Allow mixed @story/@req/@implements usage in the same comment
- * @req REQ-SCOPED-IDS - Treat requirement IDs as scoped to the referenced story file
- */
-function parseImplementsLine(line) {
-    const parts = line.split(/\s+/);
-    const storyPath = parts[IMPLEMENTS_TOKENS.STORY_INDEX];
-    const reqIds = parts.slice(IMPLEMENTS_TOKENS.FIRST_REQ_INDEX);
-    if (!storyPath || reqIds.length === 0) {
-        return null;
-    }
-    return { storyPath, reqIds };
-}
-/**
- * Validate an @supports annotation line against the referenced story content.
- * Performs path validation, file reading, caching, and requirement existence checks
- * for each requirement ID listed on the line.
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-VALIDATE - Validate that all @supports requirement IDs exist
- * @req REQ-MIXED-SUPPORT - Ensure @supports can coexist with @story/@req annotations
- * @req REQ-SCOPED-IDS - Validate requirement IDs in the scope of their explicit story
- */
-function validateImplementsLine(opts) {
-    const { comment, context, line, cwd, reqCache } = opts;
-    const parsed = parseImplementsLine(line);
-    if (!parsed) {
-        return;
-    }
-    const { storyPath, reqIds } = parsed;
-    const { reqSet } = resolveStoryAndRequirements({
-        comment,
-        context,
-        storyPath,
-        cwd,
-        reqCache,
-    });
-    if (!reqSet) {
-        return;
-    }
-    for (const reqId of reqIds) {
-        checkRequirementExists({
-            comment,
-            context,
-            reqId,
-            storyPath,
-            reqSet,
-        });
-    }
-}
-/**
- * Handle a single annotation line for story or requirement metadata.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Parse annotation lines for @story and @req tags
- * @req REQ-DEEP-MATCH - Dispatch @req lines for validation against story requirements
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-VALIDATE - Dispatch @supports lines for validation
- * @req REQ-MIXED-SUPPORT - Support mixed annotation types without interfering with each other
- */
-function handleAnnotationLine(opts) {
-    const { line, comment, context, cwd, reqCache, storyPath } = opts;
-    if (line.startsWith("@story")) {
-        const newPath = extractStoryPath(comment);
-        return newPath || storyPath;
-    }
-    else if (line.startsWith("@req")) {
-        validateReqLine({ comment, context, line, storyPath, cwd, reqCache });
-        return storyPath;
-    }
-    else if (line.startsWith("@supports")) {
-        validateImplementsLine({ comment, context, line, cwd, reqCache });
-        return storyPath;
-    }
-    return storyPath;
-}
-/**
- * Iterate over all raw lines in a comment and update storyPath as needed.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Iterate comment lines to process @story/@req annotations
- * @req REQ-DEEP-MATCH - Coordinate annotation handling across a comment block
- */
-function processCommentLines(opts) {
-    const { comment, context, cwd, reqCache, initialStoryPath } = opts;
-    let storyPath = initialStoryPath;
-    const rawLines = comment.value.split(/\r?\n/);
-    for (const rawLine of rawLines) {
-        const line = rawLine.trim().replace(/^\*+\s*/, "");
-        storyPath = handleAnnotationLine({
-            line,
-            comment,
-            context,
-            cwd,
-            reqCache,
-            storyPath,
-        });
-    }
-    return storyPath;
-}
-/**
- * Handle JSDoc story and req annotations for a single comment block.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Iterate comment lines to process @story/@req annotations
- * @req REQ-DEEP-MATCH - Coordinate annotation handling across a comment block
- * @req REQ-DEEP-CACHE - Maintain and reuse discovered story path across comments
- */
-function handleComment(opts) {
-    const { comment, context, cwd, reqCache, rawStoryPath } = opts;
-    return processCommentLines({
-        comment,
-        context,
-        cwd,
-        reqCache,
-        initialStoryPath: rawStoryPath,
-    });
-}
-/**
- * Get all comments from source and drive comment-level handling.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Collect all comments from the source code
- * @req REQ-DEEP-MATCH - Drive comment-level handling for traceability checks
- * @req REQ-DEEP-CACHE - Reuse story path and requirement cache across comments
- */
-function processAllComments(opts) {
-    const { sourceCode, context, cwd, reqCache } = opts;
-    let rawStoryPath = opts.initialStoryPath;
-    const comments = sourceCode.getAllComments() || [];
-    comments.forEach((comment) => {
-        rawStoryPath = handleComment({
-            comment,
-            context,
-            cwd,
-            reqCache,
-            rawStoryPath,
-        });
-    });
-}
-/**
- * Create a Program listener that iterates comments and validates annotations.
- * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-CACHE - Initialize and share a requirement cache for the program
- * @req REQ-DEEP-PATH - Derive the working directory context for path resolution
- */
-function programListener(context) {
-    const sourceCode = context.getSourceCode();
-    const cwd = process.cwd();
-    const reqCache = new Map();
-    let rawStoryPath = null;
-    /**
-     * Program visitor that walks all comments to validate story/requirement references.
-     * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
-     * @req REQ-DEEP-PARSE - Collect all comments from the source code
-     * @req REQ-DEEP-MATCH - Drive comment-level handling for traceability checks
-     * @req REQ-DEEP-CACHE - Reuse story path and requirement cache across comments
-     * @req REQ-DEEP-PATH - Ensure validation respects project-relative paths
-     */
-    return function Program() {
-        processAllComments({
-            sourceCode,
-            context,
-            cwd,
-            reqCache,
-            initialStoryPath: rawStoryPath,
-        });
-    };
-}
+const valid_req_reference_helpers_1 = require("./helpers/valid-req-reference-helpers");
 exports.default = {
     meta: {
         type: "problem",
@@ -372,13 +30,11 @@ exports.default = {
     },
     /**
      * Rule create entrypoint that returns the Program visitor.
-     * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
-     * @req REQ-DEEP-MATCH - Register the Program visitor with ESLint
-     * @req REQ-DEEP-PARSE - Integrate comment parsing into the ESLint rule lifecycle
-     * @req REQ-DEEP-CACHE - Ensure cache and context are wired into the listener
-     * @req REQ-DEEP-PATH - Propagate path context into the program listener
+     * Delegates to createValidReqReferenceProgramVisitor helper.
      */
     create(context) {
-        return { Program: programListener(context) };
+        return {
+            Program: (0, valid_req_reference_helpers_1.createValidReqReferenceProgramVisitor)(context),
+        };
     },
 };

package/lib/src/rules/valid-story-reference.d.ts

@@ -1,5 +1,5 @@
 /**
- * Rule to validate @story annotation references refer to existing story files
+ * This rule validates that @story annotation references refer to existing story files.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
  * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration

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

@@ -21,7 +21,7 @@ function reportInvalidPath(opts) {
     });
 }
 /**
- * Extract the story path from the annotation line and delegate validation.
+ * Extracts the story path from the annotation line and delegates validation.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-ANNOTATION-VALIDATION - Ensure each annotation line is parsed
  */
@@ -42,7 +42,7 @@ function validateStoryPath(opts) {
     });
 }
 /**
- * Handle existence status and report appropriate diagnostics for missing
+ * Handles existence status and reports appropriate diagnostics for missing
  * or filesystem-error conditions, assuming project-boundary checks have
  * already been applied.
  *
@@ -85,7 +85,7 @@ function reportExistenceStatus(existenceResult, storyPath, commentNode, context)
     }
 }
 /**
- * Report any problems related to the existence or accessibility of the
+ * Reports any problems related to the existence or accessibility of the
  * referenced story file. Filesystem and I/O errors are surfaced with a
  * dedicated diagnostic that differentiates them from missing files.
  *
@@ -115,7 +115,7 @@ function reportExistenceProblems(opts) {
     reportExistenceStatus(existenceResult, storyPath, commentNode, context);
 }
 /**
- * Process and validate the story path for security, extension, and existence.
+ * Processes and validates the story path for security, extension, and existence.
  * Filesystem and I/O errors are handled inside the underlying utilities
  * (e.g. storyExists) and surfaced as missing-file or filesystem-error
  * diagnostics where appropriate.
@@ -149,9 +149,9 @@ function processStoryPath(opts) {
         return;
     }
     /**
-     * Existence check:
-     * - Distinguish between missing files and filesystem errors.
-     * - Filesystem and I/O errors are surfaced with a dedicated diagnostic.
+     * Performs the existence check:
+     * - Distinguishes between missing files and filesystem errors.
+     * - Surfaces filesystem and I/O errors with a dedicated diagnostic.
      *
      * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
      * @req REQ-FILE-EXISTENCE - Ensure referenced files exist
@@ -166,7 +166,8 @@ function processStoryPath(opts) {
     });
 }
 /**
- * Handle a single comment node by processing its lines.
+ * Handles a single comment node by processing its lines and looking for
+ * @story annotations that should be validated.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-ANNOTATION-VALIDATION - Ensure each annotation line is parsed
  */
@@ -175,6 +176,7 @@ function handleComment(opts) {
     const lines = commentNode.value
         .split(/\r?\n/)
         /**
+         * Processes each line of the comment to extract and normalize @story annotations.
          * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
          * @req REQ-ANNOTATION-VALIDATION - Ensure each annotation line is parsed
          */
@@ -202,6 +204,7 @@ exports.default = {
         },
         messages: {
             /**
+             * Reports that a referenced story file could not be 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 - Provide specific diagnostics when a referenced story file cannot be found
@@ -210,14 +213,17 @@ exports.default = {
              */
             fileMissing: "Story file '{{path}}' not found",
             /**
+             * Reports that the provided story file path has an invalid extension.
              * @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
+             * @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'",
             /**
+             * Reports that the referenced story path is invalid due to being absolute
+             * or containing unsafe traversal.
              * @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
@@ -226,6 +232,7 @@ exports.default = {
              */
             invalidPath: "Invalid story path '{{path}}'",
             /**
+             * Reports a filesystem error that occurred while validating the story file.
              * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
              * @req REQ-ERROR-HANDLING - Provide clear diagnostics for filesystem errors
              */
@@ -251,7 +258,7 @@ exports.default = {
         const requireExt = opts?.requireStoryExtension !== false;
         return {
             /**
-             * Program-level handler: iterate comments and validate @story annotations.
+             * Program-level handler: iterates comments and validates @story annotations.
              * Filesystem and I/O errors are handled by underlying utilities and
              * surfaced as missing-file or filesystem-error diagnostics where appropriate.
              *

package/lib/src/utils/branch-annotation-helpers.d.ts

@@ -23,7 +23,7 @@ export declare function validateBranchTypes(context: Rule.RuleContext): BranchTy
  */
 export declare function gatherBranchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;
 /**
- * Report missing @story annotation on a branch node.
+ * Report missing @story annotation tag on a branch node when that branch lacks a corresponding @story reference in its comments.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  */
@@ -35,7 +35,7 @@ export declare function reportMissingStory(context: Rule.RuleContext, node: any,
     };
 }): void;
 /**
- * Report missing @req annotation on a branch node.
+ * Report missing @req annotation tag on a branch node when that branch has no linked requirement identifier in its associated comments.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  */

package/lib/src/utils/branch-annotation-helpers.js

@@ -78,6 +78,61 @@ function validateBranchTypes(context) {
         ? options.branchTypes
         : Array.from(exports.DEFAULT_BRANCH_TYPES);
 }
+/**
+ * Extract the raw value from a comment node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
+ */
+function extractCommentValue(_c) {
+    return _c.value;
+}
+/**
+ * Gather annotation text for CatchClause nodes, supporting both before-catch and inside-catch positions.
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+ * @req REQ-DUAL-POSITION-DETECTION
+ * @req REQ-FALLBACK-LOGIC
+ */
+function gatherCatchClauseCommentText(sourceCode, node, beforeText) {
+    if (/@story\b/.test(beforeText) || /@req\b/.test(beforeText)) {
+        return beforeText;
+    }
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (node.body && typeof getCommentsInside === "function") {
+        try {
+            const insideComments = getCommentsInside(node.body) || [];
+            const insideText = insideComments.map(extractCommentValue).join(" ");
+            if (insideText) {
+                return insideText;
+            }
+        }
+        catch {
+            // fall through to line-based fallback
+        }
+    }
+    if (node.body && node.body.loc && node.body.loc.start && node.body.loc.end) {
+        const lines = sourceCode.lines;
+        const startIndex = node.body.loc.start.line - 1;
+        const endIndex = node.body.loc.end.line - 1;
+        const comments = [];
+        let i = startIndex + 1;
+        while (i <= endIndex) {
+            const line = lines[i];
+            if (!line || !line.trim()) {
+                break;
+            }
+            if (!/^\s*(\/\/|\/\*)/.test(line)) {
+                break;
+            }
+            comments.push(line.trim());
+            i++;
+        }
+        const insideText = comments.join(" ");
+        if (insideText) {
+            return insideText;
+        }
+    }
+    return beforeText;
+}
 /**
  * Gather leading comment text for a branch node.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -102,19 +157,15 @@ function gatherBranchCommentText(sourceCode, node) {
         }
         return comments.join(" ");
     }
-    const comments = sourceCode.getCommentsBefore(node) || [];
-    /**
-     * Mapper to extract the text value from a comment node.
-     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-     * @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
-     */
-    function commentToValue(c) {
-        return c.value;
+    const beforeComments = sourceCode.getCommentsBefore(node) || [];
+    const beforeText = beforeComments.map(extractCommentValue).join(" ");
+    if (node.type === "CatchClause") {
+        return gatherCatchClauseCommentText(sourceCode, node, beforeText);
     }
-    return comments.map(commentToValue).join(" ");
+    return beforeText;
 }
 /**
- * Report missing @story annotation on a branch node.
+ * Report missing @story annotation tag on a branch node when that branch lacks a corresponding @story reference in its comments.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  */
@@ -127,7 +178,7 @@ function reportMissingStory(context, node, options) {
      */
     if (storyFixCountRef.count === 0) {
         /**
-         * Fixer that inserts a default @story annotation above the branch.
+         * Fixer that inserts a default @story tag above the branch.
          * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
          * @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer function used to insert missing @story
          */
@@ -151,7 +202,7 @@ function reportMissingStory(context, node, options) {
     }
 }
 /**
- * Report missing @req annotation on a branch node.
+ * Report missing @req annotation tag on a branch node when that branch has no linked requirement identifier in its associated comments.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  */
@@ -164,12 +215,12 @@ function reportMissingReq(context, node, options) {
      */
     if (!missingStory) {
         /**
-         * Fixer that inserts a default @req annotation above the branch.
+         * Fixer that inserts a default @req tag above the branch.
          * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
          * @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer function used to insert missing @req
          */
-        function insertReqFixer(fixer) {
-            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`);
+        function insertReqFixer(fxer) {
+            return fxer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`);
         }
         context.report({
             node,
@@ -195,11 +246,39 @@ function getBranchAnnotationInfo(sourceCode, node) {
     const text = gatherBranchCommentText(sourceCode, node);
     const missingStory = !/@story\b/.test(text);
     const missingReq = !/@req\b/.test(text);
-    const indent = sourceCode.lines[node.loc.start.line - 1].match(/^(\s*)/)?.[1] || "";
-    const insertPos = sourceCode.getIndexFromLoc({
+    let indent = sourceCode.lines[node.loc.start.line - 1].match(/^(\s*)/)?.[1] || "";
+    let insertPos = sourceCode.getIndexFromLoc({
         line: node.loc.start.line,
         column: 0,
     });
+    if (node.type === "CatchClause" && node.body) {
+        const bodyNode = node.body;
+        const bodyStatements = Array.isArray(bodyNode.body)
+            ? bodyNode.body
+            : undefined;
+        const firstStatement = bodyStatements && bodyStatements.length > 0
+            ? bodyStatements[0]
+            : undefined;
+        if (firstStatement && firstStatement.loc && firstStatement.loc.start) {
+            const firstLine = firstStatement.loc.start.line;
+            const innerIndent = sourceCode.lines[firstLine - 1].match(/^(\s*)/)?.[1] || "";
+            indent = innerIndent;
+            insertPos = sourceCode.getIndexFromLoc({
+                line: firstLine,
+                column: 0,
+            });
+        }
+        else if (bodyNode.loc && bodyNode.loc.start) {
+            const blockLine = bodyNode.loc.start.line;
+            const blockIndent = sourceCode.lines[blockLine - 1].match(/^(\s*)/)?.[1] || "";
+            const innerIndent = `${blockIndent}  `;
+            indent = innerIndent;
+            insertPos = sourceCode.getIndexFromLoc({
+                line: blockLine,
+                column: 0,
+            });
+        }
+    }
     return { missingStory, missingReq, indent, insertPos };
 }
 /**

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

@@ -40,6 +40,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("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)");
+        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, such as docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md");
     });
 });