eslint-plugin-traceability 1.3.0 → 1.4.1

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

@@ -11,59 +11,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
  * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
  */
-const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const storyReferenceUtils_1 = require("../utils/storyReferenceUtils");
 const defaultStoryDirs = ["docs/stories", "stories"];
-const fileExistCache = new Map();
 /**
- * Build possible file paths for a given storyPath.
+ * Extract the story path from the annotation line and delegate validation.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
- * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
- */
-function buildCandidates(storyPath, cwd, storyDirs) {
-    const candidates = [];
-    if (storyPath.startsWith("./") || storyPath.startsWith("../")) {
-        candidates.push(path_1.default.resolve(cwd, storyPath));
-    }
-    else {
-        candidates.push(path_1.default.resolve(cwd, storyPath));
-        for (const dir of storyDirs) {
-            candidates.push(path_1.default.resolve(cwd, dir, path_1.default.basename(storyPath)));
-        }
-    }
-    return candidates;
-}
-/**
- * Check if any of the candidate files exist.
- * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
- * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-ANNOTATION-VALIDATION - Ensure each annotation line is parsed
  */
-function existsAny(paths) {
-    for (const candidate of paths) {
-        let ok = fileExistCache.get(candidate);
-        if (ok === undefined) {
-            ok = fs_1.default.existsSync(candidate) && fs_1.default.statSync(candidate).isFile();
-            fileExistCache.set(candidate, ok);
-        }
-        if (ok) {
-            return true;
-        }
-    }
-    return false;
+function validateStoryPath(opts) {
+    const { line, commentNode, context, cwd, storyDirs, allowAbsolute, requireExt, } = opts;
+    const parts = line.split(/\s+/);
+    const storyPath = parts[1];
+    if (!storyPath)
+        return;
+    processStoryPath({
+        storyPath,
+        commentNode,
+        context,
+        cwd,
+        storyDirs,
+        allowAbsolute,
+        requireExt,
+    });
 }
 /**
- * Validate a single @story annotation line.
+ * Process and validate the story path for security, extension, and existence.
  * @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
  */
-function validateStoryPath(line, commentNode, context, cwd, storyDirs, allowAbsolute, requireExt) {
-    const parts = line.split(/\s+/);
-    const storyPath = parts[1];
-    if (!storyPath) {
-        return;
-    }
+function processStoryPath(opts) {
+    const { storyPath, commentNode, context, cwd, storyDirs, allowAbsolute, requireExt, } = opts;
     // Absolute path check
     if (path_1.default.isAbsolute(storyPath)) {
         if (!allowAbsolute) {
@@ -75,10 +55,9 @@ function validateStoryPath(line, commentNode, context, cwd, storyDirs, allowAbso
         }
         return;
     }
-    // Path traversal prevention
-    if (storyPath.includes("..")) {
-        const normalized = path_1.default.normalize(storyPath);
-        const full = path_1.default.resolve(cwd, normalized);
+    // 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,
@@ -89,7 +68,7 @@ function validateStoryPath(line, commentNode, context, cwd, storyDirs, allowAbso
         }
     }
     // Extension check
-    if (requireExt && !storyPath.endsWith(".story.md")) {
+    if (requireExt && !(0, storyReferenceUtils_1.hasValidExtension)(storyPath)) {
         context.report({
             node: commentNode,
             messageId: "invalidExtension",
@@ -97,9 +76,8 @@ function validateStoryPath(line, commentNode, context, cwd, storyDirs, allowAbso
         });
         return;
     }
-    // Build candidate paths and check existence
-    const candidates = buildCandidates(storyPath, cwd, storyDirs);
-    if (!existsAny(candidates)) {
+    // Existence check
+    if (!(0, storyReferenceUtils_1.normalizeStoryPath)(storyPath, cwd, storyDirs).exists) {
         context.report({
             node: commentNode,
             messageId: "fileMissing",
@@ -112,13 +90,22 @@ function validateStoryPath(line, commentNode, context, cwd, storyDirs, allowAbso
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-ANNOTATION-VALIDATION - Ensure each annotation line is parsed
  */
-function handleComment(commentNode, context, sourceCode, cwd, storyDirs, allowAbsolute, requireExt) {
+function handleComment(opts) {
+    const { commentNode, context, cwd, storyDirs, allowAbsolute, requireExt } = opts;
     const lines = commentNode.value
         .split(/\r?\n/)
         .map((l) => l.replace(/^[^@]*/, "").trim());
     for (const line of lines) {
         if (line.startsWith("@story")) {
-            validateStoryPath(line, commentNode, context, cwd, storyDirs, allowAbsolute, requireExt);
+            validateStoryPath({
+                line,
+                commentNode,
+                context,
+                cwd,
+                storyDirs,
+                allowAbsolute,
+                requireExt,
+            });
         }
     }
 }
@@ -138,10 +125,7 @@ exports.default = {
             {
                 type: "object",
                 properties: {
-                    storyDirectories: {
-                        type: "array",
-                        items: { type: "string" },
-                    },
+                    storyDirectories: { type: "array", items: { type: "string" } },
                     allowAbsolutePaths: { type: "boolean" },
                     requireStoryExtension: { type: "boolean" },
                 },
@@ -150,17 +134,30 @@ exports.default = {
         ],
     },
     create(context) {
-        const sourceCode = context.getSourceCode();
         const cwd = process.cwd();
         const opts = context.options[0];
         const storyDirs = opts?.storyDirectories || defaultStoryDirs;
         const allowAbsolute = opts?.allowAbsolutePaths || false;
         const requireExt = opts?.requireStoryExtension !== false;
         return {
+            /**
+             * Program-level handler: iterate comments and validate @story annotations.
+             * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+             * @req REQ-ANNOTATION-VALIDATION - Discover and dispatch @story annotations for validation
+             * @req REQ-FILE-EXISTENCE - Ensure referenced files exist
+             * @req REQ-PATH-RESOLUTION - Resolve using cwd and configured story directories
+             */
             Program() {
-                const comments = sourceCode.getAllComments() || [];
+                const comments = context.getSourceCode().getAllComments() || [];
                 for (const comment of comments) {
-                    handleComment(comment, context, sourceCode, cwd, storyDirs, allowAbsolute, requireExt);
+                    handleComment({
+                        commentNode: comment,
+                        context,
+                        cwd,
+                        storyDirs,
+                        allowAbsolute,
+                        requireExt,
+                    });
                 }
             },
         };

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

@@ -1,6 +1,80 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkReqAnnotation = checkReqAnnotation;
+/**
+ * Helper to retrieve the JSDoc comment for a node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-GET-JSDOC - Retrieve JSDoc comment for a node
+ */
+function getJsdocComment(sourceCode, node) {
+    return sourceCode.getJSDocComment(node);
+}
+/**
+ * Helper to retrieve leading comments from a node (TypeScript declare style).
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-LEADING-COMMENTS - Collect leading comments from node
+ */
+function getLeadingComments(node) {
+    return node.leadingComments || [];
+}
+/**
+ * Helper to retrieve comments before a node using the sourceCode API.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-COMMENTS-BEFORE - Collect comments before node via sourceCode
+ */
+function getCommentsBefore(sourceCode, node) {
+    return sourceCode.getCommentsBefore(node) || [];
+}
+/**
+ * Helper to combine leading and before comments into a single array.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-COMBINE-COMMENTS - Combine comment arrays for checking
+ */
+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");
+}
+/**
+ * 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) {
+    return ((jsdoc &&
+        typeof jsdoc.value === "string" &&
+        jsdoc.value.includes("@req")) ||
+        comments.some(commentContainsReq));
+}
+/**
+ * Creates a fix function that inserts a missing @req JSDoc before the node.
+ * Returned function is a proper named function so no inline arrow is used.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
+ */
+function createMissingReqFix(node) {
+    return function missingReqFix(fixer) {
+        return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
+    };
+}
+/**
+ * Helper to report a missing @req annotation via the ESLint context API.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
+ */
+function reportMissing(context, node) {
+    context.report({
+        node,
+        messageId: "missingReq",
+        fix: createMissingReqFix(node),
+    });
+}
 /**
  * Helper to check @req annotation presence on TS declare functions and method signatures.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -8,19 +82,12 @@ exports.checkReqAnnotation = checkReqAnnotation;
  */
 function checkReqAnnotation(context, node) {
     const sourceCode = context.getSourceCode();
-    const jsdoc = sourceCode.getJSDocComment(node);
-    const leading = node.leadingComments || [];
-    const comments = sourceCode.getCommentsBefore(node) || [];
-    const all = [...leading, ...comments];
-    const hasReq = (jsdoc && jsdoc.value.includes("@req")) ||
-        all.some((c) => c.value.includes("@req"));
+    const jsdoc = getJsdocComment(sourceCode, node);
+    const leading = getLeadingComments(node);
+    const comments = getCommentsBefore(sourceCode, node);
+    const all = combineComments(leading, comments);
+    const hasReq = hasReqAnnotation(jsdoc, all);
     if (!hasReq) {
-        context.report({
-            node,
-            messageId: "missingReq",
-            fix(fixer) {
-                return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
-            },
-        });
+        reportMissing(context, node);
     }
 }

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

@@ -0,0 +1,54 @@
+import type { Rule } from "eslint";
+/**
+ * Valid branch types for require-branch-annotation rule.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-SIGNIFICANCE-CRITERIA - Define criteria for which branches require annotations
+ */
+export declare const DEFAULT_BRANCH_TYPES: readonly ["IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"];
+/**
+ * Type for branch nodes supported by require-branch-annotation rule.
+ */
+export type BranchType = (typeof DEFAULT_BRANCH_TYPES)[number];
+/**
+ * Validate branchTypes configuration option and return branch types to enforce,
+ * or return an ESLint listener if configuration is invalid.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ */
+export declare function validateBranchTypes(context: Rule.RuleContext): BranchType[] | Rule.RuleListener;
+/**
+ * Gather leading comment text for a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
+ */
+export declare function gatherBranchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;
+/**
+ * Report missing @story annotation 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
+ */
+export declare function reportMissingStory(context: Rule.RuleContext, node: any, options: {
+    indent: string;
+    insertPos: number;
+    storyFixCountRef: {
+        count: number;
+    };
+}): void;
+/**
+ * Report missing @req annotation 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
+ */
+export declare function reportMissingReq(context: Rule.RuleContext, node: any, options: {
+    indent: string;
+    insertPos: number;
+    missingStory: boolean;
+}): void;
+/**
+ * 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
+ */
+export declare function reportMissingAnnotations(context: Rule.RuleContext, node: any, storyFixCountRef: {
+    count: number;
+}): void;

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

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BRANCH_TYPES = void 0;
+exports.validateBranchTypes = validateBranchTypes;
+exports.gatherBranchCommentText = gatherBranchCommentText;
+exports.reportMissingStory = reportMissingStory;
+exports.reportMissingReq = reportMissingReq;
+exports.reportMissingAnnotations = reportMissingAnnotations;
+const PRE_COMMENT_OFFSET = 2; // number of lines above branch to inspect for comments
+/**
+ * Valid branch types for require-branch-annotation rule.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-SIGNIFICANCE-CRITERIA - Define criteria for which branches require annotations
+ */
+exports.DEFAULT_BRANCH_TYPES = [
+    "IfStatement",
+    "SwitchCase",
+    "TryStatement",
+    "CatchClause",
+    "ForStatement",
+    "ForOfStatement",
+    "ForInStatement",
+    "WhileStatement",
+    "DoWhileStatement",
+];
+/**
+ * Validate branchTypes configuration option and return branch types to enforce,
+ * or return an ESLint listener if configuration is invalid.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ */
+function validateBranchTypes(context) {
+    const options = context.options[0] || {};
+    if (Array.isArray(options.branchTypes)) {
+        const invalidTypes = options.branchTypes.filter((t) => !exports.DEFAULT_BRANCH_TYPES.includes(t));
+        if (invalidTypes.length > 0) {
+            return {
+                Program(node) {
+                    invalidTypes.forEach((t) => {
+                        context.report({
+                            node,
+                            message: `Value "${t}" should be equal to one of the allowed values: ${exports.DEFAULT_BRANCH_TYPES.join(", ")}`,
+                        });
+                    });
+                },
+            };
+        }
+    }
+    return Array.isArray(options.branchTypes)
+        ? options.branchTypes
+        : Array.from(exports.DEFAULT_BRANCH_TYPES);
+}
+/**
+ * Gather leading comment text for a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
+ */
+function gatherBranchCommentText(sourceCode, node) {
+    if (node.type === "SwitchCase") {
+        const lines = sourceCode.lines;
+        const startLine = node.loc.start.line;
+        let i = startLine - PRE_COMMENT_OFFSET;
+        const comments = [];
+        while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
+            comments.unshift(lines[i].trim());
+            i--;
+        }
+        return comments.join(" ");
+    }
+    const comments = sourceCode.getCommentsBefore(node) || [];
+    return comments.map((c) => c.value).join(" ");
+}
+/**
+ * Report missing @story annotation 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 reportMissingStory(context, node, options) {
+    const { indent, insertPos, storyFixCountRef } = options;
+    if (storyFixCountRef.count === 0) {
+        context.report({
+            node,
+            messageId: "missingAnnotation",
+            data: { missing: "@story" },
+            fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`),
+        });
+        storyFixCountRef.count++;
+    }
+    else {
+        context.report({
+            node,
+            messageId: "missingAnnotation",
+            data: { missing: "@story" },
+        });
+    }
+}
+/**
+ * Report missing @req annotation 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 reportMissingReq(context, node, options) {
+    const { indent, insertPos, missingStory } = options;
+    if (!missingStory) {
+        context.report({
+            node,
+            messageId: "missingAnnotation",
+            data: { missing: "@req" },
+            fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`),
+        });
+    }
+    else {
+        context.report({
+            node,
+            messageId: "missingAnnotation",
+            data: { missing: "@req" },
+        });
+    }
+}
+/**
+ * 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 text = gatherBranchCommentText(sourceCode, node);
+    const missingStory = !/@story\b/.test(text);
+    const missingReq = !/@req\b/.test(text);
+    const indent = sourceCode.lines[node.loc.start.line - 1].match(/^(\s*)/)?.[1] || "";
+    const insertPos = sourceCode.getIndexFromLoc({
+        line: node.loc.start.line,
+        column: 0,
+    });
+    const actions = [
+        {
+            missing: missingStory,
+            fn: reportMissingStory,
+            args: [context, node, { indent, insertPos, storyFixCountRef }],
+        },
+        {
+            missing: missingReq,
+            fn: reportMissingReq,
+            args: [context, node, { indent, insertPos, missingStory }],
+        },
+    ];
+    actions.forEach(({ missing, fn, args }) => missing && fn(...args));
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Build candidate file paths for a given story path.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
+ */
+export declare function buildStoryCandidates(storyPath: string, cwd: string, storyDirs: string[]): string[];
+export declare function storyExists(paths: string[]): boolean;
+/**
+ * Normalize a story path to candidate absolute paths and check existence.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ */
+export declare function normalizeStoryPath(storyPath: string, cwd: string, storyDirs: string[]): {
+    candidates: string[];
+    exists: boolean;
+};
+/**
+ * Check if the provided path is absolute.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent absolute path usage
+ */
+export declare function isAbsolutePath(p: string): boolean;
+/**
+ * Check for path traversal patterns.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal
+ */
+export declare function containsPathTraversal(p: string): boolean;
+/**
+ * Determine if a path is unsafe due to traversal or being absolute.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
+ */
+export declare function isTraversalUnsafe(p: string): boolean;
+/**
+ * Validate that the story file has an allowed extension.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Enforce allowed file extensions
+ */
+export declare function hasValidExtension(p: string): boolean;
+/**
+ * Determine if a story path is unsafe due to traversal, being absolute, or invalid extension.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal, absolute path usage, and enforce allowed file extensions
+ */
+export declare function isUnsafeStoryPath(p: string): boolean;

package/lib/src/utils/storyReferenceUtils.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStoryCandidates = buildStoryCandidates;
+exports.storyExists = storyExists;
+exports.normalizeStoryPath = normalizeStoryPath;
+exports.isAbsolutePath = isAbsolutePath;
+exports.containsPathTraversal = containsPathTraversal;
+exports.isTraversalUnsafe = isTraversalUnsafe;
+exports.hasValidExtension = hasValidExtension;
+exports.isUnsafeStoryPath = isUnsafeStoryPath;
+/**
+ * Utility functions for story path resolution and existence checking.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Build candidate file paths for a given story path.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
+ */
+function buildStoryCandidates(storyPath, cwd, storyDirs) {
+    const candidates = [];
+    if (storyPath.startsWith("./") || storyPath.startsWith("../")) {
+        candidates.push(path_1.default.resolve(cwd, storyPath));
+    }
+    else {
+        candidates.push(path_1.default.resolve(cwd, storyPath));
+        for (const dir of storyDirs) {
+            candidates.push(path_1.default.resolve(cwd, dir, path_1.default.basename(storyPath)));
+        }
+    }
+    return candidates;
+}
+/**
+ * Check if any of the provided file paths exist.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ */
+const fileExistCache = new Map();
+function storyExists(paths) {
+    for (const candidate of paths) {
+        let ok = fileExistCache.get(candidate);
+        if (ok === undefined) {
+            ok = fs_1.default.existsSync(candidate) && fs_1.default.statSync(candidate).isFile();
+            fileExistCache.set(candidate, ok);
+        }
+        if (ok) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Normalize a story path to candidate absolute paths and check existence.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ */
+function normalizeStoryPath(storyPath, cwd, storyDirs) {
+    const candidates = buildStoryCandidates(storyPath, cwd, storyDirs);
+    const exists = storyExists(candidates);
+    return { candidates, exists };
+}
+/**
+ * Check if the provided path is absolute.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent absolute path usage
+ */
+function isAbsolutePath(p) {
+    return path_1.default.isAbsolute(p);
+}
+/**
+ * Check for path traversal patterns.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal
+ */
+function containsPathTraversal(p) {
+    const normalized = path_1.default.normalize(p);
+    return normalized.split(path_1.default.sep).includes("..");
+}
+/**
+ * Determine if a path is unsafe due to traversal or being absolute.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
+ */
+function isTraversalUnsafe(p) {
+    return isAbsolutePath(p) || containsPathTraversal(p);
+}
+/**
+ * Validate that the story file has an allowed extension.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Enforce allowed file extensions
+ */
+function hasValidExtension(p) {
+    return p.endsWith(".story.md");
+}
+/**
+ * Determine if a story path is unsafe due to traversal, being absolute, or invalid extension.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal, absolute path usage, and enforce allowed file extensions
+ */
+function isUnsafeStoryPath(p) {
+    return isTraversalUnsafe(p) || !hasValidExtension(p);
+}

package/lib/tests/cli-error-handling.test.d.ts

@@ -0,0 +1 @@
+export {};