eslint-plugin-traceability 1.6.2 → 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/rules/valid-story-reference.js

@@ -36,18 +36,37 @@ function validateStoryPath(opts) {
     });
 }
 /**
- * Report 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.
+ * 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
+ * already been applied.
  *
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-FILE-EXISTENCE - Ensure referenced files exist
  * @req REQ-ERROR-HANDLING - Differentiate missing files from filesystem errors
  */
-function reportExistenceProblems(opts) {
-    const { storyPath, commentNode, context, cwd, storyDirs } = opts;
-    const result = (0, storyReferenceUtils_1.normalizeStoryPath)(storyPath, cwd, storyDirs);
-    const existenceResult = result.existence;
+function reportExistenceStatus(existenceResult, storyPath, commentNode, context) {
     if (!existenceResult || existenceResult.status === "exists") {
         return;
     }
@@ -81,6 +100,48 @@ function reportExistenceProblems(opts) {
         });
     }
 }
+/**
+ * Report 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.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Ensure referenced files exist
+ * @req REQ-ERROR-HANDLING - Differentiate missing files from filesystem errors
+ * @req REQ-PROJECT-BOUNDARY - Ensure resolved candidate paths remain within the project root
+ * @req REQ-CONFIGURABLE-PATHS - Respect configured storyDirectories while enforcing project boundaries
+ */
+function reportExistenceProblems(opts) {
+    const { storyPath, commentNode, context, cwd, storyDirs } = 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;
+        }
+    }
+    reportExistenceStatus(existenceResult, storyPath, commentNode, context);
+}
 /**
  * Process and validate the story path for security, extension, and existence.
  * Filesystem and I/O errors are handled inside the underlying utilities
@@ -103,8 +164,10 @@ function processStoryPath(opts) {
                 messageId: "invalidPath",
                 data: { path: storyPath },
             });
+            return;
         }
-        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)) {
@@ -223,7 +286,7 @@ exports.default = {
         ],
     },
     create(context) {
-        const cwd = process.cwd();
+        const cwd = context.cwd ?? process.cwd();
         const opts = context.options[0];
         const storyDirs = opts?.storyDirectories || defaultStoryDirs;
         const allowAbsolute = opts?.allowAbsolutePaths || false;

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

@@ -31,6 +31,34 @@ export interface StoryExistenceResult {
     matchedPath?: string;
     error?: unknown;
 }
+/**
+ * Result of validating that a candidate path stays within the project boundary.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
+ */
+export interface ProjectBoundaryCheckResult {
+    candidate: string;
+    isWithinProject: boolean;
+}
+/**
+ * Validate that a candidate path stays within the project boundary.
+ * This compares the resolved candidate path against the normalized cwd
+ * prefix, ensuring that even when storyDirectories are misconfigured, we
+ * never treat files outside the project as valid story references.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
+ */
+export declare function enforceProjectBoundary(candidate: string, cwd: string): ProjectBoundaryCheckResult;
+/**
+ * Internal helper to reset the filesystem existence cache. This is primarily
+ * intended for tests that need to run multiple scenarios with different
+ * mocked filesystem behavior without carrying over cached results.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Allow safe cache reset in tests to avoid stale entries
+ */
+export declare function __resetStoryExistenceCacheForTests(): void;
 /**
  * Build candidate file paths for a given story path.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md

package/lib/src/utils/storyReferenceUtils.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceProjectBoundary = enforceProjectBoundary;
+exports.__resetStoryExistenceCacheForTests = __resetStoryExistenceCacheForTests;
 exports.buildStoryCandidates = buildStoryCandidates;
 exports.getStoryExistence = getStoryExistence;
 exports.storyExists = storyExists;
@@ -22,6 +24,36 @@ exports.isUnsafeStoryPath = isUnsafeStoryPath;
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+/**
+ * Validate that a candidate path stays within the project boundary.
+ * This compares the resolved candidate path against the normalized cwd
+ * prefix, ensuring that even when storyDirectories are misconfigured, we
+ * never treat files outside the project as valid story references.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
+ */
+function enforceProjectBoundary(candidate, cwd) {
+    const normalizedCwd = path_1.default.resolve(cwd);
+    const normalizedCandidate = path_1.default.resolve(candidate);
+    const isWithinProject = normalizedCandidate === normalizedCwd ||
+        normalizedCandidate.startsWith(normalizedCwd + path_1.default.sep);
+    return {
+        candidate: normalizedCandidate,
+        isWithinProject,
+    };
+}
+/**
+ * Internal helper to reset the filesystem existence cache. This is primarily
+ * intended for tests that need to run multiple scenarios with different
+ * mocked filesystem behavior without carrying over cached results.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Allow safe cache reset in tests to avoid stale entries
+ */
+function __resetStoryExistenceCacheForTests() {
+    fileExistStatusCache.clear();
+}
 /**
  * Build candidate file paths for a given story path.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
@@ -29,11 +61,20 @@ const path_1 = __importDefault(require("path"));
  */
 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)));
         }
@@ -59,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" };
             }
@@ -80,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);
@@ -104,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,
@@ -111,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/lib/tests/rules/valid-story-reference.test.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -16,6 +49,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const eslint_1 = require("eslint");
 const valid_story_reference_1 = __importDefault(require("../../src/rules/valid-story-reference"));
 const storyReferenceUtils_1 = require("../../src/utils/storyReferenceUtils");
+const path = __importStar(require("path"));
 const ruleTester = new eslint_1.RuleTester({
     languageOptions: { parserOptions: { ecmaVersion: 2020 } },
 });
@@ -73,6 +107,233 @@ describe("Valid Story Reference Rule (Story 006.0-DEV-FILE-VALIDATION)", () => {
         ],
     });
 });
+// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+// @req REQ-CONFIGURABLE-PATHS - Verify custom storyDirectories behavior
+const configurablePathsTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+configurablePathsTester.run("valid-story-reference", valid_story_reference_1.default, {
+    valid: [
+        {
+            name: "[REQ-CONFIGURABLE-PATHS] honors custom storyDirectories using docs/stories",
+            code: `// @story 001.0-DEV-PLUGIN-SETUP.story.md\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [{ storyDirectories: ["docs/stories"] }],
+        },
+    ],
+    invalid: [],
+});
+// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+// @req REQ-CONFIGURABLE-PATHS - Verify allowAbsolutePaths behavior
+const allowAbsolutePathsTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+const absoluteStoryPath = path.resolve(process.cwd(), "docs/stories/001.0-DEV-PLUGIN-SETUP.story.md");
+allowAbsolutePathsTester.run("valid-story-reference", valid_story_reference_1.default, {
+    valid: [
+        {
+            name: "[REQ-CONFIGURABLE-PATHS] allowAbsolutePaths accepts existing absolute .story.md inside project",
+            code: `// @story ${absoluteStoryPath}\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [
+                {
+                    allowAbsolutePaths: true,
+                    storyDirectories: ["docs/stories"],
+                },
+            ],
+        },
+    ],
+    invalid: [
+        {
+            name: "[REQ-CONFIGURABLE-PATHS] disallows absolute paths when allowAbsolutePaths is false",
+            code: `// @story ${absoluteStoryPath}\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [
+                {
+                    allowAbsolutePaths: false,
+                    storyDirectories: ["docs/stories"],
+                },
+            ],
+            errors: [
+                {
+                    messageId: "invalidPath",
+                },
+            ],
+        },
+    ],
+});
+// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+// @req REQ-CONFIGURABLE-PATHS - Verify requireStoryExtension behavior
+const relaxedExtensionTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+relaxedExtensionTester.run("valid-story-reference", valid_story_reference_1.default, {
+    valid: [
+        {
+            name: "[REQ-CONFIGURABLE-PATHS] accepts .story.md story path when requireStoryExtension is false (still valid and existing)",
+            code: `// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [
+                {
+                    storyDirectories: ["docs/stories"],
+                    requireStoryExtension: false,
+                },
+            ],
+        },
+    ],
+    invalid: [],
+});
+// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+// @req REQ-PROJECT-BOUNDARY - Verify project boundary handling
+const projectBoundaryTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+projectBoundaryTester.run("valid-story-reference", valid_story_reference_1.default, {
+    valid: [],
+    invalid: [
+        {
+            name: "[REQ-PROJECT-BOUNDARY] story reference outside project root is rejected when discovered via absolute path",
+            code: `// @story ${path.resolve(path.sep, "outside-project", "001.0-DEV-PLUGIN-SETUP.story.md")}\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [
+                {
+                    allowAbsolutePaths: true,
+                    storyDirectories: [path.resolve(path.sep, "outside-project")],
+                },
+            ],
+            errors: [
+                {
+                    messageId: "invalidPath",
+                },
+            ],
+        },
+    ],
+});
+describe("Valid Story Reference Rule Configuration and Boundaries (Story 006.0-DEV-FILE-VALIDATION)", () => {
+    const fs = require("fs");
+    const pathModule = require("path");
+    let tempDirs = [];
+    afterEach(() => {
+        for (const dir of tempDirs) {
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // ignore cleanup errors
+            }
+        }
+        tempDirs = [];
+        (0, storyReferenceUtils_1.__resetStoryExistenceCacheForTests)();
+        jest.restoreAllMocks();
+    });
+    it("[REQ-CONFIGURABLE-PATHS] uses storyDirectories when resolving relative paths (Story 006.0-DEV-FILE-VALIDATION)", () => {
+        const storyPath = pathModule.join(process.cwd(), "docs/stories/001.0-DEV-PLUGIN-SETUP.story.md");
+        jest.spyOn(fs, "existsSync").mockImplementation((...args) => {
+            const p = args[0];
+            return p === storyPath;
+        });
+        jest.spyOn(fs, "statSync").mockImplementation((...args) => {
+            const p = args[0];
+            if (p === storyPath) {
+                return {
+                    isFile: () => true,
+                };
+            }
+            throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
+        const diagnostics = runRuleOnCode(`// @story 001.0-DEV-PLUGIN-SETUP.story.md`, [{ storyDirectories: ["docs/stories"] }]);
+        // When storyDirectories is configured, the underlying resolution should
+        // treat the path as valid; absence of errors is asserted via RuleTester
+        // above. Here we just ensure no crash path via storyExists cache reset.
+        expect(Array.isArray(diagnostics)).toBe(true);
+    });
+    it("[REQ-CONFIGURABLE-PATHS] allowAbsolutePaths permits absolute paths inside project when enabled (Story 006.0-DEV-FILE-VALIDATION)", () => {
+        const absPath = pathModule.resolve(process.cwd(), "docs/stories/001.0-DEV-PLUGIN-SETUP.story.md");
+        const diagnostics = runRuleOnCode(`// @story ${absPath}`, [
+            {
+                allowAbsolutePaths: true,
+                storyDirectories: ["docs/stories"],
+            },
+        ]);
+        // Detailed behavior is verified by RuleTester above; this Jest test
+        // ensures helper path construction does not throw and diagnostics are collected.
+        expect(Array.isArray(diagnostics)).toBe(true);
+    });
+    it("[REQ-PROJECT-BOUNDARY] storyDirectories cannot escape project even when normalize resolves outside cwd (Story 006.0-DEV-FILE-VALIDATION)", () => {
+        const ruleModule = require("../../src/rules/valid-story-reference");
+        const originalCreate = ruleModule.default.create || ruleModule.create;
+        // Spy on create to intercept normalizeStoryPath behavior indirectly if needed
+        expect(typeof originalCreate).toBe("function");
+        const diagnostics = runRuleOnCode(`// @story ../outside-boundary.story.md\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`);
+        // Behavior of reporting invalidPath for outside project is ensured
+        // in RuleTester projectBoundaryTester above; here ensure diagnostics collected.
+        expect(Array.isArray(diagnostics)).toBe(true);
+    });
+    /**
+     * @req REQ-PROJECT-BOUNDARY - Verify misconfigured storyDirectories pointing outside
+     * the project cannot cause external files to be treated as valid, and invalidPath is reported.
+     * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+     */
+    it("[REQ-PROJECT-BOUNDARY] misconfigured storyDirectories outside project cannot validate external files", () => {
+        const fs = require("fs");
+        const pathModule = require("path");
+        const outsideDir = pathModule.resolve(pathModule.sep, "tmp", "outside");
+        const outsideFile = pathModule.join(outsideDir, "external-story.story.md");
+        jest.spyOn(fs, "existsSync").mockImplementation((...args) => {
+            const p = args[0];
+            return p === outsideFile;
+        });
+        jest.spyOn(fs, "statSync").mockImplementation((...args) => {
+            const p = args[0];
+            if (p === outsideFile) {
+                return {
+                    isFile: () => true,
+                };
+            }
+            const err = new Error("ENOENT");
+            err.code = "ENOENT";
+            throw err;
+        });
+        const diagnostics = runRuleOnCode(`// @story ${outsideFile}\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`, [
+            {
+                allowAbsolutePaths: true,
+                storyDirectories: [outsideDir],
+            },
+        ]);
+        expect(Array.isArray(diagnostics)).toBe(true);
+        const invalidPathDiagnostics = diagnostics.filter((d) => d.messageId === "invalidPath");
+        expect(invalidPathDiagnostics.length).toBeGreaterThan(0);
+    });
+    /**
+     * @req REQ-CONFIGURABLE-PATHS - Verify requireStoryExtension: false allows .md story
+     * files that do not end with .story.md when they exist in storyDirectories.
+     * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+     */
+    it("[REQ-CONFIGURABLE-PATHS] requireStoryExtension=false accepts existing .md story file", () => {
+        const fs = require("fs");
+        const pathModule = require("path");
+        const storyPath = pathModule.join(process.cwd(), "docs/stories/developer-story.map.md");
+        jest.spyOn(fs, "existsSync").mockImplementation((...args) => {
+            const p = args[0];
+            return p === storyPath;
+        });
+        jest.spyOn(fs, "statSync").mockImplementation((...args) => {
+            const p = args[0];
+            if (p === storyPath) {
+                return {
+                    isFile: () => true,
+                };
+            }
+            const err = new Error("ENOENT");
+            err.code = "ENOENT";
+            throw err;
+        });
+        const diagnostics = runRuleOnCode(`// @story docs/stories/developer-story.map.md\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`, [
+            {
+                storyDirectories: ["docs/stories"],
+                requireStoryExtension: false,
+            },
+        ]);
+        expect(Array.isArray(diagnostics)).toBe(true);
+        const invalidExtensionDiagnostics = diagnostics.filter((d) => d.messageId === "invalidExtension");
+        expect(invalidExtensionDiagnostics.length).toBe(0);
+    });
+});
 /**
  * Helper to run the valid-story-reference rule against a single source string
  * and collect reported diagnostics.
@@ -80,7 +341,7 @@ describe("Valid Story Reference Rule (Story 006.0-DEV-FILE-VALIDATION)", () => {
  * @req REQ-ERROR-HANDLING - Used to verify fileAccessError reporting behavior
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  */
-function runRuleOnCode(code) {
+function runRuleOnCode(code, options = []) {
     const messages = [];
     const context = {
         report: (descriptor) => {
@@ -95,7 +356,7 @@ function runRuleOnCode(code) {
                 },
             ],
         }),
-        options: [],
+        options,
         parserOptions: { ecmaVersion: 2020 },
     };
     const listeners = valid_story_reference_1.default.create(context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.6.2",
+  "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",