eslint-plugin-traceability 1.11.0 → 1.11.2

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/annotation-checker.js

@@ -90,6 +90,34 @@ function createMissingReqFix(node) {
         return fixer.insertTextBefore(target, "/** @req <REQ-ID> */\n");
     };
 }
+/**
+ * Resolve the display name used when reporting a missing @req annotation.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REPORTING - Use consistent naming when reporting missing @req
+ * @req REQ-ERROR-SPECIFIC - Derive a specific, human-readable name for the node
+ */
+function getReportedName(contextNode, parentNode) {
+    const rawName = (0, require_story_utils_1.getNodeName)(contextNode) ?? (0, require_story_utils_1.getNodeName)(parentNode);
+    return rawName ?? "(anonymous)";
+}
+/**
+ * Determine the AST sub-node that should be used as the location for reporting.
+ * Prefers Identifier nodes (id or key) over the broader function-like node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REPORTING - Report missing @req on the most relevant node
+ * @req REQ-ERROR-SPECIFIC - Target the identifier when available for precise errors
+ */
+function getNameNodeForReqReport(node) {
+    const candidateId = node.id;
+    if (candidateId && candidateId.type === "Identifier") {
+        return candidateId;
+    }
+    const candidateKey = node.key;
+    if (candidateKey && candidateKey.type === "Identifier") {
+        return candidateKey;
+    }
+    return node;
+}
 /**
  * Helper to report a missing @req annotation via the ESLint context API.
  * Uses getNodeName to provide a readable name for the node.
@@ -102,13 +130,9 @@ function createMissingReqFix(node) {
  * @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 parentNode = node?.parent;
+    const name = getReportedName(node, parentNode);
+    const nameNode = getNameNodeForReqReport(node);
     const reportOptions = {
         node: nameNode,
         messageId: "missingReq",

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

@@ -114,7 +114,7 @@ function gatherBranchCommentText(sourceCode, node) {
     return comments.map(commentToValue).join(" ");
 }
 /**
- * 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 +127,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 +151,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,7 +164,7 @@ 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
          */

package/lib/src/utils/reqAnnotationDetection.js

@@ -138,6 +138,38 @@ function fallbackTextBeforeHasReq(sourceCode, node) {
     }
     return false;
 }
+/**
+ * Helper to combine advanced, location-based heuristics for requirement detection.
+ * Uses preceding lines, parent-chain comments, and fallback text windows to find @req/@supports.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-ANNOTATION-REQ-DETECTION - Use multiple heuristics to detect @req markers around the node
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Use multiple heuristics to detect @supports markers around the node
+ */
+function hasReqInAdvancedHeuristics(sourceCode, node) {
+    if (!sourceCode || !node) {
+        return false;
+    }
+    return (linesBeforeHasReq(sourceCode, node) ||
+        parentChainHasReq(sourceCode, node) ||
+        fallbackTextBeforeHasReq(sourceCode, node));
+}
+/**
+ * Helper to check JSDoc and nearby comments for requirement annotations.
+ * Accepts both @req and @supports markers as evidence of requirement coverage.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation in JSDoc/comments
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @supports as requirement coverage in JSDoc/comments
+ */
+function hasReqInJsdocOrComments(jsdoc, comments) {
+    if (jsdoc &&
+        typeof jsdoc.value === "string" &&
+        (jsdoc.value.includes("@req") || jsdoc.value.includes("@supports"))) {
+        return true;
+    }
+    return comments.some(commentContainsReq);
+}
 /**
  * Helper to determine whether a JSDoc or any nearby comments contain a requirement annotation.
  * Treats both @req and @supports annotations as evidence of requirement coverage.
@@ -151,30 +183,12 @@ function hasReqAnnotation(jsdoc, comments, context, node) {
         const sourceCode = context && typeof context.getSourceCode === "function"
             ? context.getSourceCode()
             : undefined;
-        // Prefer robust, location-based heuristics when sourceCode and node are available.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Use multiple heuristics to detect @req markers around the node
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Use multiple heuristics to detect @supports markers around the node
-        if (sourceCode && node) {
-            if (linesBeforeHasReq(sourceCode, node) ||
-                parentChainHasReq(sourceCode, node) ||
-                fallbackTextBeforeHasReq(sourceCode, node)) {
-                return true;
-            }
+        if (hasReqInAdvancedHeuristics(sourceCode, node)) {
+            return true;
         }
     }
     catch {
-        // Swallow detection errors and fall through to simple checks.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Fail gracefully when advanced detection heuristics throw
+        // swallow and fall through to simple checks
     }
-    // BRANCH requirement detection on JSDoc or comments, accepting both @req and @supports.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
-    // @req REQ-ANNOTATION-REQ-DETECTION
-    // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS
-    return ((jsdoc &&
-        typeof jsdoc.value === "string" &&
-        (jsdoc.value.includes("@req") || jsdoc.value.includes("@supports"))) ||
-        comments.some(commentContainsReq));
+    return hasReqInJsdocOrComments(jsdoc, comments);
 }

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

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for CLI error handling when plugin loading fails
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-ERROR-HANDLING - Plugin CLI should exit with error on rule load failure
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-ERROR-HANDLING
  */
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
@@ -39,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");
     });
 });