eslint-plugin-traceability 1.6.5 → 1.7.0

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

@@ -31,28 +31,20 @@ function extractStoryPath(comment) {
     return null;
 }
 /**
- * Validate a @req annotation line against the extracted story content.
- * Performs path validation, file reading, caching, and requirement existence checks.
+ * 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
- * @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 parts = line.split(/\s+/);
-    const reqId = parts[1];
-    if (!reqId || !storyPath) {
-        return;
-    }
+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;
+        return null;
     }
     const resolvedStoryPath = path_1.default.resolve(cwd, storyPath);
     if (!resolvedStoryPath.startsWith(cwd + path_1.default.sep) &&
@@ -62,8 +54,19 @@ function validateReqLine(opts) {
             messageId: "invalidPath",
             data: { storyPath },
         });
-        return;
+        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");
@@ -79,7 +82,15 @@ function validateReqLine(opts) {
             reqCache.set(resolvedStoryPath, new Set());
         }
     }
-    const reqSet = reqCache.get(resolvedStoryPath);
+    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,
@@ -88,6 +99,71 @@ function validateReqLine(opts) {
         });
     }
 }
+/**
+ * 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,
+    });
+}
 /**
  * Handle a single annotation line for story or requirement metadata.
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
@@ -107,15 +183,14 @@ function handleAnnotationLine(opts) {
     return storyPath;
 }
 /**
- * Handle JSDoc story and req annotations for a single comment block.
+ * 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
- * @req REQ-DEEP-CACHE - Maintain and reuse discovered story path across comments
  */
-function handleComment(opts) {
-    const { comment, context, cwd, reqCache, rawStoryPath } = opts;
-    let storyPath = rawStoryPath;
+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*/, "");
@@ -130,6 +205,44 @@ function handleComment(opts) {
     }
     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
@@ -150,15 +263,12 @@ function programListener(context) {
      * @req REQ-DEEP-PATH - Ensure validation respects project-relative paths
      */
     return function Program() {
-        const comments = sourceCode.getAllComments() || [];
-        comments.forEach((comment) => {
-            rawStoryPath = handleComment({
-                comment,
-                context,
-                cwd,
-                reqCache,
-                rawStoryPath,
-            });
+        processAllComments({
+            sourceCode,
+            context,
+            cwd,
+            reqCache,
+            initialStoryPath: rawStoryPath,
         });
     };
 }

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

@@ -1,3 +1,10 @@
+/**
+ * Rule to validate @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
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
+ */
 import type { Rule } from "eslint";
 declare const _default: Rule.RuleModule;
 export default _default;

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

@@ -1,19 +1,25 @@
 "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 */
+const storyReferenceUtils_1 = require("../utils/storyReferenceUtils");
+const valid_story_reference_helpers_1 = require("./helpers/valid-story-reference-helpers");
+const defaultStoryDirs = ["docs/stories", "stories"];
 /**
- * Rule to validate @story annotation references refer to existing story files
+ * Shared helper to report an invalid story path. Centralizes the
+ * `invalidPath` diagnostic so callers don't repeat the same
+ * `context.report` shape.
+ *
  * @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
- * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
+ * @req REQ-PROJECT-BOUNDARY - Ensure resolved candidate paths remain within the project root
+ * @req REQ-ERROR-CONSISTENCY - Maintain a consistent template for invalid path diagnostics across rules
  */
-const path_1 = __importDefault(require("path"));
-const storyReferenceUtils_1 = require("../utils/storyReferenceUtils");
-const defaultStoryDirs = ["docs/stories", "stories"];
+function reportInvalidPath(opts) {
+    const { storyPath, commentNode, context } = opts;
+    context.report({
+        node: commentNode,
+        messageId: "invalidPath",
+        data: { path: storyPath },
+    });
+}
 /**
  * Extract the story path from the annotation line and delegate validation.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
@@ -35,28 +41,6 @@ function validateStoryPath(opts) {
         requireExt,
     });
 }
-/**
- * Analyze candidate paths against the project boundary, returning whether any
- * are within the project and whether any are outside.
- *
- * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
- * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
- * @req REQ-CONFIGURABLE-PATHS - Respect configured storyDirectories while enforcing project boundaries
- */
-function analyzeCandidateBoundaries(candidates, cwd) {
-    let hasInProjectCandidate = false;
-    let hasOutOfProjectCandidate = false;
-    for (const candidate of candidates) {
-        const boundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(candidate, cwd);
-        if (boundary.isWithinProject) {
-            hasInProjectCandidate = true;
-        }
-        else {
-            hasOutOfProjectCandidate = true;
-        }
-    }
-    return { hasInProjectCandidate, hasOutOfProjectCandidate };
-}
 /**
  * Handle existence status and report appropriate diagnostics for missing
  * or filesystem-error conditions, assuming project-boundary checks have
@@ -116,29 +100,17 @@ function reportExistenceProblems(opts) {
     const result = (0, storyReferenceUtils_1.normalizeStoryPath)(storyPath, cwd, storyDirs);
     const existenceResult = result.existence;
     const candidates = result.candidates || [];
-    if (candidates.length > 0) {
-        const { hasInProjectCandidate, hasOutOfProjectCandidate } = analyzeCandidateBoundaries(candidates, cwd);
-        if (hasOutOfProjectCandidate && !hasInProjectCandidate) {
-            context.report({
-                node: commentNode,
-                messageId: "invalidPath",
-                data: { path: storyPath },
-            });
-            return;
-        }
-    }
-    if (existenceResult &&
-        existenceResult.status === "exists" &&
-        existenceResult.matchedPath) {
-        const boundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(existenceResult.matchedPath, cwd);
-        if (!boundary.isWithinProject) {
-            context.report({
-                node: commentNode,
-                messageId: "invalidPath",
-                data: { path: storyPath },
-            });
-            return;
-        }
+    const invalidByBoundary = (0, valid_story_reference_helpers_1.handleProjectBoundaryForExistence)({
+        storyPath,
+        commentNode,
+        context,
+        cwd,
+        candidates,
+        existenceResult,
+        reportInvalidPath,
+    });
+    if (invalidByBoundary) {
+        return;
     }
     reportExistenceStatus(existenceResult, storyPath, commentNode, context);
 }
@@ -156,30 +128,16 @@ function reportExistenceProblems(opts) {
  */
 function processStoryPath(opts) {
     const { storyPath, commentNode, context, cwd, storyDirs, allowAbsolute, requireExt, } = opts;
-    // Absolute path check
-    if (path_1.default.isAbsolute(storyPath)) {
-        if (!allowAbsolute) {
-            context.report({
-                node: commentNode,
-                messageId: "invalidPath",
-                data: { path: storyPath },
-            });
-            return;
-        }
-        // When absolute paths are allowed, we still enforce extension and
-        // project-boundary checks below via the existence phase.
-    }
-    // Path traversal check
-    if ((0, storyReferenceUtils_1.containsPathTraversal)(storyPath)) {
-        const full = path_1.default.resolve(cwd, path_1.default.normalize(storyPath));
-        if (!full.startsWith(cwd + path_1.default.sep)) {
-            context.report({
-                node: commentNode,
-                messageId: "invalidPath",
-                data: { path: storyPath },
-            });
-            return;
-        }
+    const securityOk = (0, valid_story_reference_helpers_1.performSecurityValidations)({
+        storyPath,
+        commentNode,
+        context,
+        cwd,
+        allowAbsolute,
+        reportInvalidPath,
+    });
+    if (!securityOk) {
+        return;
     }
     // Extension check
     if (requireExt && !(0, storyReferenceUtils_1.hasValidExtension)(storyPath)) {

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

@@ -2,7 +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");
+const reqAnnotationDetection_1 = require("./reqAnnotationDetection");
 /**
  * Helper to retrieve the JSDoc comment for a node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -35,149 +35,6 @@ function getCommentsBefore(sourceCode, node) {
 function combineComments(leading, before) {
     return [...leading, ...before];
 }
-/**
- * Predicate helper to check whether a comment contains a @req annotation.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-CHECK-COMMENT - Detect @req tag inside a comment
- */
-function commentContainsReq(c) {
-    return c && typeof c.value === "string" && c.value.includes("@req");
-}
-/**
- * Line-based helper adapted from linesBeforeHasStory to detect @req.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req in preceding source lines
- */
-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;
-    // Guard against missing or malformed source/loc information before scanning.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQ-DETECTION - Avoid false positives when sourceCode/loc is incomplete
-    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);
-    // Scan each physical line in the configured lookback window for an @req marker.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQ-DETECTION - Search preceding lines for @req text
-    for (let i = from; i < to; i++) {
-        const text = lines[i];
-        // When a line contains @req we treat the function as already annotated.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req marker in raw source lines
-        if (typeof text === "string" && text.includes("@req")) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Parent-chain helper adapted from parentChainHasStory to detect @req.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req in parent-chain comments
- */
-function parentChainHasReq(sourceCode, node) {
-    let p = node && node.parent;
-    // Walk up the parent chain and inspect comments attached to each ancestor.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQ-DETECTION - Traverse parent nodes when local comments are absent
-    while (p) {
-        const pComments = typeof sourceCode?.getCommentsBefore === "function"
-            ? sourceCode.getCommentsBefore(p) || []
-            : [];
-        // Look for @req in comments immediately preceding each parent node.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req markers in parent comments
-        if (Array.isArray(pComments) && pComments.some(commentContainsReq)) {
-            return true;
-        }
-        const pLeading = p.leadingComments || [];
-        // Also inspect leadingComments attached directly to the parent node.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req markers in parent leadingComments
-        if (Array.isArray(pLeading) && pLeading.some(commentContainsReq)) {
-            return true;
-        }
-        p = p.parent;
-    }
-    return false;
-}
-/**
- * Fallback text window helper adapted from fallbackTextBeforeHasStory to detect @req.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req in fallback text window before node
- */
-function fallbackTextBeforeHasReq(sourceCode, node) {
-    // Guard against unsupported sourceCode or nodes without a usable range.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQ-DETECTION - Ensure we only inspect text when range information is available
-    if (typeof sourceCode?.getText !== "function" ||
-        !Array.isArray((node && node.range) || [])) {
-        return false;
-    }
-    const range = node.range;
-    // Guard when the node range cannot provide a numeric start index.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQ-DETECTION - Avoid scanning when range start is not a number
-    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]);
-        // Detect @req in the bounded text window immediately preceding the node.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req marker in fallback text window
-        if (typeof textBefore === "string" && textBefore.includes("@req")) {
-            return true;
-        }
-    }
-    catch {
-        // Swallow detection errors to avoid breaking lint runs due to malformed source.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Treat IO/detection failures as "no annotation" instead of throwing
-        /* 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, context, node) {
-    try {
-        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
-        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.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Fail gracefully when advanced detection heuristics throw
-    }
-    // BRANCH @req detection on JSDoc or comments
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQ-DETECTION
-    return ((jsdoc &&
-        typeof jsdoc.value === "string" &&
-        jsdoc.value.includes("@req")) ||
-        comments.some(commentContainsReq));
-}
 /**
  * Determine the most appropriate node to attach an inserted JSDoc to.
  * Prefers outer function-like constructs such as methods, variable declarators,
@@ -283,7 +140,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, context, node);
+    const hasReq = (0, reqAnnotationDetection_1.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/src/utils/branch-annotation-helpers.js

@@ -187,12 +187,11 @@ function reportMissingReq(context, node, options) {
     }
 }
 /**
- * Report missing annotations on a branch node.
+ * Compute annotation-related metadata for a branch node.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  */
-function reportMissingAnnotations(context, node, storyFixCountRef) {
-    const sourceCode = context.getSourceCode();
+function getBranchAnnotationInfo(sourceCode, node) {
     const text = gatherBranchCommentText(sourceCode, node);
     const missingStory = !/@story\b/.test(text);
     const missingReq = !/@req\b/.test(text);
@@ -201,6 +200,16 @@ function reportMissingAnnotations(context, node, storyFixCountRef) {
         line: node.loc.start.line,
         column: 0,
     });
+    return { missingStory, missingReq, indent, insertPos };
+}
+/**
+ * Report missing annotations on a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
+ */
+function reportMissingAnnotations(context, node, storyFixCountRef) {
+    const sourceCode = context.getSourceCode();
+    const { missingStory, missingReq, indent, insertPos } = getBranchAnnotationInfo(sourceCode, node);
     const actions = [
         {
             missing: missingStory,

package/lib/src/utils/reqAnnotationDetection.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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
+ */
+export declare function hasReqAnnotation(jsdoc: any, comments: any[], context?: any, node?: any): boolean;