eslint-plugin-traceability 1.6.3 → 1.6.4

package/lib/src/maintenance/detect.js

@@ -37,37 +37,107 @@ exports.detectStaleAnnotations = detectStaleAnnotations;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const utils_1 = require("./utils");
+const storyReferenceUtils_1 = require("../utils/storyReferenceUtils");
 /**
  * Detect stale annotation references that point to moved or deleted story files
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
  */
 function detectStaleAnnotations(codebasePath) {
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-DETECT - Ensure codebase path exists and is a directory
-    if (!fs.existsSync(codebasePath) ||
-        !fs.statSync(codebasePath).isDirectory()) {
+    const cwd = process.cwd();
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Treat codebasePath as a workspace root resolved from process.cwd()
+    const workspaceRoot = path.resolve(cwd, codebasePath);
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Return empty result if workspaceRoot does not exist or is not a directory
+    if (!fs.existsSync(workspaceRoot) ||
+        !fs.statSync(workspaceRoot).isDirectory()) {
         return [];
     }
-    const cwd = process.cwd();
-    const baseDir = path.resolve(cwd, codebasePath);
     const stale = new Set();
-    const files = (0, utils_1.getAllFiles)(codebasePath);
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-DETECT - Iterate over all files in the codebase
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Iterate over all files in the isolated workspace root
+    const files = (0, utils_1.getAllFiles)(workspaceRoot);
     for (const file of files) {
-        const content = fs.readFileSync(file, "utf8");
-        const regex = /@story\s+([^\s]+)/g;
-        let match;
-        // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-DETECT - Iterate over regex matches for @story annotations
-        while ((match = regex.exec(content)) !== null) {
-            const storyPath = match[1];
-            const storyProjectPath = path.resolve(cwd, storyPath);
-            const storyCodebasePath = path.resolve(baseDir, storyPath);
-            // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-DETECT - Check if referenced story file is missing in both project and codebase paths
-            if (!fs.existsSync(storyProjectPath) &&
-                !fs.existsSync(storyCodebasePath)) {
-                stale.add(storyPath);
-            }
-        }
+        processFileForStaleAnnotations(file, workspaceRoot, cwd, stale);
     }
     return Array.from(stale);
 }
+/**
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-DETECT - Process individual files to detect stale @story annotations
+ */
+function processFileForStaleAnnotations(file, workspaceRoot, cwd, stale) {
+    let content;
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Handle file read errors gracefully
+    try {
+        content = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return;
+    }
+    const regex = /@story\s+([^\s]+)/g;
+    let match;
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Iterate over regex matches for @story annotations
+    while ((match = regex.exec(content)) !== null) {
+        handleStoryMatch(match[1], workspaceRoot, cwd, stale);
+    }
+}
+/**
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-DETECT - Handle individual @story matches within a file
+ */
+function handleStoryMatch(storyPath, workspaceRoot, cwd, stale) {
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Skip traversal/absolute-unsafe story paths before any filesystem or boundary checks
+    if ((0, storyReferenceUtils_1.isTraversalUnsafe)(storyPath)) {
+        return;
+    }
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Compute project and codebase candidates relative to cwd and workspaceRoot
+    const storyProjectCandidate = path.resolve(cwd, storyPath);
+    const storyCodebaseCandidate = path.resolve(workspaceRoot, storyPath);
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Enforce workspaceRoot as the project boundary for resolved story paths
+    let projectBoundary;
+    let codebaseBoundary;
+    try {
+        projectBoundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(storyProjectCandidate, workspaceRoot);
+    }
+    catch {
+        projectBoundary = {
+            isWithinProject: false,
+            candidate: storyProjectCandidate,
+        };
+    }
+    try {
+        codebaseBoundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(storyCodebaseCandidate, workspaceRoot);
+    }
+    catch {
+        codebaseBoundary = {
+            isWithinProject: false,
+            candidate: storyCodebaseCandidate,
+        };
+    }
+    const inProjectCandidates = [];
+    if (projectBoundary.isWithinProject) {
+        inProjectCandidates.push(projectBoundary.candidate);
+    }
+    if (codebaseBoundary.isWithinProject) {
+        inProjectCandidates.push(codebaseBoundary.candidate);
+    }
+    // If both candidates are out-of-project, do not mark as stale and skip FS checks
+    if (inProjectCandidates.length === 0) {
+        return;
+    }
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Only check existence for in-project candidates
+    const anyExists = inProjectCandidates.some((p) => fs.existsSync(p));
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - Mark story as stale if any in-project candidate exists conceptually but none exist on disk
+    if (!anyExists) {
+        stale.add(storyPath);
+    }
+}

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

@@ -31,13 +31,22 @@ function linesBeforeHasStory(sourceCode, node, lookback = exports.LOOKBACK_LINES
     const startLine = node && node.loc && typeof node.loc.start?.line === "number"
         ? node.loc.start.line
         : null;
+    // Guard against missing or non-array source lines or an invalid start line before scanning.
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED - Fail gracefully when source lines or locations are unavailable
     if (!Array.isArray(lines) || typeof startLine !== "number") {
         return false;
     }
     const from = Math.max(0, startLine - 1 - lookback);
     const to = Math.max(0, startLine - 1);
+    // Walk each physical line in the configured lookback window to search for an inline @story marker.
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED - Scan preceding lines for existing story annotations
     for (let i = from; i < to; i++) {
         const text = lines[i];
+        // Treat any line containing "@story" as evidence that the function is already annotated.
+        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+        // @req REQ-ANNOTATION-REQUIRED - Detect explicit @story markers in raw source text
         if (typeof text === "string" && text.includes("@story")) {
             return true;
         }
@@ -84,24 +93,39 @@ function parentChainHasStory(sourceCode, node) {
  * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
  */
 function fallbackTextBeforeHasStory(sourceCode, node) {
+    // Skip fallback text inspection when the sourceCode API or node range information is not available.
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED - Avoid throwing when source text or range metadata cannot be read
     if (typeof sourceCode?.getText !== "function" ||
         !Array.isArray((node && node.range) || [])) {
         return false;
     }
     const range = node.range;
+    // Guard against malformed range values that cannot provide a numeric start index for slicing.
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED - Validate node range structure before computing fallback window
     if (!Array.isArray(range) || typeof range[0] !== "number") {
         return false;
     }
     try {
-        // Limit the fallback inspect window to a reasonable size
+        // Limit the fallback inspection window to a bounded region immediately preceding the node.
+        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+        // @req REQ-ANNOTATION-REQUIRED - Restrict fallback text scanning to a safe, fixed-size window
         const start = Math.max(0, range[0] - exports.FALLBACK_WINDOW);
         const textBefore = sourceCode.getText().slice(start, range[0]);
+        // Detect any @story marker that appears within the bounded fallback window.
+        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+        // @req REQ-ANNOTATION-REQUIRED - Recognize story annotations discovered via fallback text scanning
         if (typeof textBefore === "string" && textBefore.includes("@story")) {
             return true;
         }
     }
     catch {
-        /* noop */
+        /*
+         * Swallow low-level IO or slicing errors so annotation detection never breaks lint execution.
+         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+         * @req REQ-ANNOTATION-REQUIRED - Treat fallback text inspection failures as "no annotation" instead of raising
+         */
     }
     return false;
 }

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

@@ -26,7 +26,7 @@
  * Get a readable name for a given AST node.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-ANNOTATION-REQUIRED - Provide a unified way to obtain a stable, human-readable name from AST nodes
  *
  * @param node - An AST node (ESTree/TSESTree/JSX-like). Can be null/undefined.
  * @returns The resolved name string, or null if a stable name cannot be determined.

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

@@ -29,7 +29,7 @@ exports.getNodeName = getNodeName;
  * Check for identifier-like nodes and return their name when available.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-ANNOTATION-REQUIRED - Recognize Identifier/JSXIdentifier nodes and return their name
  *
  * @param node - AST node to inspect
  * @returns the identifier name or null
@@ -47,7 +47,7 @@ function isIdentifierLike(node) {
  * Convert a Literal node to a string when it represents a stable primitive (string/number/boolean).
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-ANNOTATION-REQUIRED - Convert simple Literal nodes into stable string names when possible
  *
  * @param node - AST node expected to be a Literal
  * @returns the literal as string or null if not stable/resolvable
@@ -67,7 +67,7 @@ function literalToString(node) {
  * Convert a TemplateLiteral node to a string if it contains no expressions.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-ANNOTATION-REQUIRED - Support simple, expression-free TemplateLiteral names for reporting
  *
  * @param node - AST node expected to be a TemplateLiteral
  * @returns the cooked/raw concatenated template string or null if it contains expressions
@@ -95,7 +95,7 @@ function templateLiteralToString(node) {
  * Resolve a MemberExpression / TSQualifiedName / JSXMemberExpression-like node to a name when non-computed.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-ANNOTATION-REQUIRED - Resolve non-computed member-like nodes into property names when safe
  *
  * @param node - AST node to inspect
  * @returns resolved member/property name or null
@@ -121,7 +121,7 @@ function memberExpressionName(node) {
  * Extract the key name from Property/ObjectProperty nodes.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-ANNOTATION-REQUIRED - Extract key names from Property/ObjectProperty nodes used in function containers
  *
  * @param node - AST node expected to be Property/ObjectProperty
  * @returns the resolved key name or null
@@ -141,7 +141,7 @@ function propertyKeyName(node) {
  * Branch-level traceability: prefer direct .key.name early (common on variable declarators, properties)
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-ANNOTATION-REQUIRED - Prefer direct id/key names before falling back to deeper AST inspection
  *
  * @param node - AST node to inspect for direct .id/.key name
  * @returns the resolved direct name or null
@@ -173,7 +173,7 @@ function directName(node) {
  * Get a readable name for a given AST node.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-ANNOTATION-REQUIRED - Provide a unified way to obtain a stable, human-readable name from AST nodes
  *
  * @param node - An AST node (ESTree/TSESTree/JSX-like). Can be null/undefined.
  * @returns The resolved name string, or null if a stable name cannot be determined.

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

@@ -13,6 +13,12 @@ const require_story_helpers_1 = require("./require-story-helpers");
  * @req REQ-BUILD-VISITORS-FNDECL - Provide visitor for FunctionDeclaration
  */
 function buildFunctionDeclarationVisitor(context, sourceCode, options) {
+    /**
+     * Debug flag for optional visitor logging.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-DEBUG-LOG-TOGGLE - Allow opt-in debug logging via TRACEABILITY_DEBUG
+     */
+    const debugEnabled = process.env.TRACEABILITY_DEBUG === "1";
     /**
      * Handle FunctionDeclaration nodes.
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -24,9 +30,11 @@ function buildFunctionDeclarationVisitor(context, sourceCode, options) {
          * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
          * @req REQ-DEBUG-LOG - Provide debug logging for visitor entry
          */
-        console.debug("require-story-annotation:FunctionDeclaration", typeof context.getFilename === "function"
-            ? context.getFilename()
-            : "<unknown>", node && node.id ? node.id.name : "<anonymous>");
+        if (debugEnabled) {
+            console.debug("require-story-annotation:FunctionDeclaration", typeof context.getFilename === "function"
+                ? context.getFilename()
+                : "<unknown>", node && node.id ? node.id.name : "<anonymous>");
+        }
         if (!options.shouldProcessNode(node))
             return;
         const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);

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

@@ -63,15 +63,25 @@ const rule = {
         const opts = (context.options && context.options[0]) || {};
         const scope = opts.scope || require_story_helpers_1.DEFAULT_SCOPE;
         const exportPriority = opts.exportPriority || "all";
+        /**
+         * Environment-gated debug logging to avoid leaking file paths unless
+         * explicitly enabled.
+         *
+         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+         * @req REQ-DEBUG-LOG
+         */
+        const debugEnabled = process.env.TRACEABILITY_DEBUG === "1";
         /**
          * Debug log at the start of create to help diagnose rule activation in tests.
          *
          * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
          * @req REQ-DEBUG-LOG
          */
-        console.debug("require-story-annotation:create", typeof context.getFilename === "function"
-            ? context.getFilename()
-            : "<unknown>");
+        if (debugEnabled) {
+            console.debug("require-story-annotation:create", typeof context.getFilename === "function"
+                ? context.getFilename()
+                : "<unknown>");
+        }
         // Local closure that binds configured scope and export priority to the helper.
         const should = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority);
         // Delegate visitor construction to helper to keep this file concise.

package/lib/src/utils/annotation-checker.d.ts

@@ -6,6 +6,10 @@
  * @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
+ * @param context - ESLint rule context used to obtain source and report problems
+ * @param node - Function-like AST node whose surrounding comments should be inspected
+ * @param options - Optional configuration controlling behaviour (e.g., enableFix)
+ * @returns void
  */
 export declare function checkReqAnnotation(context: any, node: any, options?: {
     enableFix?: boolean;

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

@@ -45,19 +45,30 @@ function commentContainsReq(c) {
 }
 /**
  * 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;
         }
@@ -66,20 +77,29 @@ function linesBeforeHasReq(sourceCode, node) {
 }
 /**
  * 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) || []
             : [];
-        if (Array.isArray(pComments) &&
-            pComments.some((c) => typeof c.value === "string" && c.value.includes("@req"))) {
+        // 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 || [];
-        if (Array.isArray(pLeading) &&
-            pLeading.some((c) => typeof c.value === "string" && c.value.includes("@req"))) {
+        // 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;
@@ -88,24 +108,38 @@ function parentChainHasReq(sourceCode, node) {
 }
 /**
  * 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;
@@ -120,6 +154,9 @@ 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
         if (sourceCode && node) {
             if (linesBeforeHasReq(sourceCode, node) ||
                 parentChainHasReq(sourceCode, node) ||
@@ -130,6 +167,8 @@ function hasReqAnnotation(jsdoc, comments, context, node) {
     }
     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
@@ -148,19 +187,28 @@ function hasReqAnnotation(jsdoc, comments, context, node) {
  */
 function getFixTargetNode(node) {
     const parent = node && node.parent;
+    // When there is no parent, attach the annotation directly to the node itself.
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-AUTOFIX - Default to annotating the node when it has no parent
     if (!parent) {
         return node;
     }
     // If the node is part of a class/obj method definition, attach to the MethodDefinition
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-AUTOFIX - Attach fixes to the MethodDefinition wrapper for methods
     if (parent.type === "MethodDefinition") {
         return parent;
     }
     // If the node is the init of a variable declarator, attach to the VariableDeclarator
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-AUTOFIX - Attach fixes to the VariableDeclarator for function initializers
     if (parent.type === "VariableDeclarator" && parent.init === node) {
         return parent;
     }
     // If the parent is an expression statement (e.g. IIFE or assigned via expression),
     // attach to the outer ExpressionStatement.
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-AUTOFIX - Attach fixes to the ExpressionStatement wrapper for IIFEs
     if (parent.type === "ExpressionStatement") {
         return parent;
     }
@@ -174,6 +222,11 @@ function getFixTargetNode(node) {
  */
 function createMissingReqFix(node) {
     const target = getFixTargetNode(node);
+    /**
+     * Fixer used to insert a default @req annotation before the chosen target node.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
+     */
     return function missingReqFix(fixer) {
         return fixer.insertTextBefore(target, "/** @req <REQ-ID> */\n");
     };
@@ -202,6 +255,9 @@ function reportMissing(context, node, enableFix = true) {
         messageId: "missingReq",
         data: { name, functionName: name },
     };
+    // Conditionally attach an autofix only when enabled in the rule options.
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-AUTOFIX - Only provide autofix suggestions when explicitly enabled
     if (enableFix) {
         reportOptions.fix = createMissingReqFix(node);
     }
@@ -215,6 +271,10 @@ function reportMissing(context, node, enableFix = true) {
  * @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
+ * @param context - ESLint rule context used to obtain source and report problems
+ * @param node - Function-like AST node whose surrounding comments should be inspected
+ * @param options - Optional configuration controlling behaviour (e.g., enableFix)
+ * @returns void
  */
 function checkReqAnnotation(context, node, options) {
     const { enableFix = true } = options ?? {};

package/lib/src/utils/storyReferenceUtils.js

@@ -61,11 +61,20 @@ function __resetStoryExistenceCacheForTests() {
  */
 function buildStoryCandidates(storyPath, cwd, storyDirs) {
     const candidates = [];
+    // When the story path is already explicitly relative, resolve it only against the current working directory.
+    // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+    // @req REQ-PATH-RESOLUTION - Preserve explicit relative story path semantics when building candidate locations
     if (storyPath.startsWith("./") || storyPath.startsWith("../")) {
         candidates.push(path_1.default.resolve(cwd, storyPath));
     }
     else {
+        // For bare paths, first try resolving directly under the current working directory.
+        // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+        // @req REQ-PATH-RESOLUTION - Attempt direct resolution from cwd before probing configured story directories
         candidates.push(path_1.default.resolve(cwd, storyPath));
+        // Probe each configured story directory for a matching story filename.
+        // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+        // @req REQ-PATH-RESOLUTION - Expand search across configured storyDirectories while staying within project
         for (const dir of storyDirs) {
             candidates.push(path_1.default.resolve(cwd, dir, path_1.default.basename(storyPath)));
         }
@@ -91,17 +100,26 @@ const fileExistStatusCache = new Map();
  */
 function checkSingleCandidate(candidate) {
     const cached = fileExistStatusCache.get(candidate);
+    // Reuse any cached filesystem result to avoid redundant disk IO for the same candidate.
+    // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+    // @req REQ-PERFORMANCE-OPTIMIZATION - Short-circuit on cached existence checks
     if (cached) {
         return cached;
     }
     let result;
     try {
         const exists = fs_1.default.existsSync(candidate);
+        // When the path does not exist at all, record a simple "missing" status.
+        // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+        // @req REQ-FILE-EXISTENCE - Distinguish non-existent story paths from other failure modes
         if (!exists) {
             result = { path: candidate, status: "missing" };
         }
         else {
             const stat = fs_1.default.statSync(candidate);
+            // Treat existing regular files as valid story candidates; other entry types are considered missing.
+            // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+            // @req REQ-FILE-EXISTENCE - Only regular files may satisfy a story path reference
             if (stat.isFile()) {
                 result = { path: candidate, status: "exists" };
             }
@@ -112,7 +130,9 @@ function checkSingleCandidate(candidate) {
         }
     }
     catch (error) {
-        // Any filesystem error is captured and surfaced as fs-error.
+        // Any filesystem error is captured and surfaced as an fs-error status instead of throwing.
+        // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+        // @req REQ-ERROR-HANDLING - Represent filesystem failures as fs-error results while keeping callers resilient
         result = { path: candidate, status: "fs-error", error };
     }
     fileExistStatusCache.set(candidate, result);
@@ -136,6 +156,9 @@ function getStoryExistence(candidates) {
     let firstFsError;
     for (const candidate of candidates) {
         const res = checkSingleCandidate(candidate);
+        // As soon as a candidate file is confirmed to exist, return a successful existence result.
+        // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+        // @req REQ-FILE-EXISTENCE - Prefer the first positively-matched story file
         if (res.status === "exists") {
             return {
                 candidates,
@@ -143,10 +166,16 @@ function getStoryExistence(candidates) {
                 matchedPath: res.path,
             };
         }
+        // Remember the first filesystem error so callers can inspect a representative failure if no files exist.
+        // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+        // @req REQ-ERROR-HANDLING - Surface a single representative filesystem error without failing fast
         if (res.status === "fs-error" && !firstFsError) {
             firstFsError = res;
         }
     }
+    // Prefer reporting a filesystem error over a generic missing status when at least one candidate failed to read.
+    // @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+    // @req REQ-ERROR-HANDLING - Distinguish IO failures from simple "missing" results in existence checks
     if (firstFsError) {
         return {
             candidates,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.6.3",
+  "version": "1.6.4",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",