eslint-plugin-traceability 1.3.0 → 1.4.1

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

@@ -1,184 +1,206 @@
 "use strict";
-/**
- * Rule to enforce @story annotation on functions, function expressions, arrow functions, and methods
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Require @story annotation on functions
- * @req REQ-OPTIONS-SCOPE - Support configuring which function types to enforce via options
- * @req REQ-EXPORT-PRIORITY - Add exportPriority option to target exported or non-exported
- * @req REQ-UNIFIED-CHECK - Implement unified checkNode for all supported node types
- * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
- * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
- */
 Object.defineProperty(exports, "__esModule", { value: true });
+// Default node types to check for function annotations
+const DEFAULT_SCOPE = [
+    "FunctionDeclaration",
+    "FunctionExpression",
+    "ArrowFunctionExpression",
+    "MethodDefinition",
+    "TSDeclareFunction",
+    "TSMethodSignature",
+];
+const EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
 /**
- * Determine if a node is exported via export declaration.
+ * Determine if a node is in an export declaration
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-EXPORT-PRIORITY - Determine if function node has export declaration ancestor
+ * @req REQ-ANNOTATION-REQUIRED
+ * @param {any} node - AST node to check for export ancestry
+ * @returns {boolean} true if node is within an export declaration
  */
 function isExportedNode(node) {
-    let current = node;
-    while (current) {
-        if (current.type === "ExportNamedDeclaration" ||
-            current.type === "ExportDefaultDeclaration") {
+    let p = node.parent;
+    while (p) {
+        if (p.type === "ExportNamedDeclaration" ||
+            p.type === "ExportDefaultDeclaration") {
             return true;
         }
-        current = current.parent;
+        p = p.parent;
     }
     return false;
 }
+// Path to the story file for annotations
+const STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
+const ANNOTATION = `/** @story ${STORY_PATH} */`;
 /**
- * Find nearest ancestor node of specified types.
+ * Check if @story annotation already present in JSDoc or preceding comments
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-OPTIONS-SCOPE - Support configuring which function types to enforce via options
+ * @req REQ-ANNOTATION-REQUIRED
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - AST node to inspect for existing annotations
+ * @returns {boolean} true if @story annotation already present
  */
-function findAncestorNode(node, types) {
-    let current = node.parent;
-    while (current) {
-        if (types.includes(current.type)) {
-            return current;
-        }
-        current = current.parent;
+function hasStoryAnnotation(sourceCode, node) {
+    const jsdoc = sourceCode.getJSDocComment(node);
+    if (jsdoc?.value.includes("@story")) {
+        return true;
     }
-    return null;
+    const comments = sourceCode.getCommentsBefore(node) || [];
+    return comments.some((c) => c.value.includes("@story"));
 }
 /**
- * Determine if node should be checked based on scope and exportPriority.
+ * Get the name of the function-like node
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-OPTIONS-SCOPE
- * @req REQ-EXPORT-PRIORITY
- * @req REQ-UNIFIED-CHECK
+ * @req REQ-ANNOTATION-REQUIRED
+ * @param {any} node - AST node representing a function-like construct
+ * @returns {string} the resolved name or "<unknown>"
  */
-function shouldCheckNode(node, scope, exportPriority) {
-    if (node.type === "FunctionExpression" &&
-        node.parent?.type === "MethodDefinition") {
-        return false;
-    }
-    if (!scope.includes(node.type)) {
-        return false;
-    }
-    const exported = isExportedNode(node);
-    if ((exportPriority === "exported" && !exported) ||
-        (exportPriority === "non-exported" && exported)) {
-        return false;
+function getNodeName(node) {
+    let current = node;
+    while (current) {
+        if (current.type === "VariableDeclarator" &&
+            current.id &&
+            typeof current.id.name === "string") {
+            return current.id.name;
+        }
+        if ((current.type === "FunctionDeclaration" ||
+            current.type === "TSDeclareFunction") &&
+            current.id &&
+            typeof current.id.name === "string") {
+            return current.id.name;
+        }
+        if ((current.type === "MethodDefinition" ||
+            current.type === "TSMethodSignature") &&
+            current.key &&
+            typeof current.key.name === "string") {
+            return current.key.name;
+        }
+        current = current.parent;
     }
-    return true;
+    return "<unknown>";
 }
 /**
- * Resolve the AST node to annotate or check.
+ * Determine AST node where annotation should be inserted
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-UNIFIED-CHECK
+ * @req REQ-ANNOTATION-REQUIRED
+ * @param {any} sourceCode - ESLint sourceCode object (unused but kept for parity)
+ * @param {any} node - function-like AST node to resolve target for
+ * @returns {any} AST node that should receive the annotation
  */
 function resolveTargetNode(sourceCode, node) {
-    let target = node;
-    if (node.type === "FunctionDeclaration") {
-        const exp = findAncestorNode(node, [
-            "ExportNamedDeclaration",
-            "ExportDefaultDeclaration",
-        ]);
-        if (exp) {
-            target = exp;
-        }
+    if (node.type === "TSMethodSignature") {
+        // Interface method signature -> insert on interface
+        return node.parent.parent;
     }
-    else if (node.type === "FunctionExpression" ||
+    if (node.type === "FunctionExpression" ||
         node.type === "ArrowFunctionExpression") {
-        const exp = findAncestorNode(node, [
-            "ExportNamedDeclaration",
-            "ExportDefaultDeclaration",
-        ]);
-        if (exp) {
-            target = exp;
-        }
-        else {
-            const anc = findAncestorNode(node, [
-                "VariableDeclaration",
-                "ExpressionStatement",
-            ]);
-            if (anc) {
-                target = anc;
+        const parent = node.parent;
+        if (parent.type === "VariableDeclarator") {
+            const varDecl = parent.parent;
+            if (varDecl.parent && varDecl.parent.type === "ExportNamedDeclaration") {
+                return varDecl.parent;
             }
+            return varDecl;
         }
-    }
-    else if (node.type === "TSMethodSignature") {
-        const exp = findAncestorNode(node, ["TSInterfaceDeclaration"]);
-        if (exp) {
-            target = exp;
+        if (parent.type === "ExportNamedDeclaration") {
+            return parent;
+        }
+        if (parent.type === "ExpressionStatement") {
+            return parent;
         }
     }
-    else if (node.type === "MethodDefinition") {
-        target = node;
-    }
-    return target;
+    return node;
 }
 /**
- * Check if the target node has @story annotation.
+ * Report missing @story annotation on function or method
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED
+ * @param {Rule.RuleContext} context - ESLint rule context
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - function AST node missing annotation
+ * @param {any} target - AST node where annotation should be inserted
  */
-function hasStoryAnnotation(sourceCode, target) {
-    const jsdoc = sourceCode.getJSDocComment(target);
-    if (jsdoc?.value.includes("@story")) {
-        return true;
+function reportMissing(context, sourceCode, node, target) {
+    if (hasStoryAnnotation(sourceCode, node) ||
+        hasStoryAnnotation(sourceCode, target)) {
+        return;
     }
-    const comments = sourceCode.getCommentsBefore(target) || [];
-    return comments.some((c) => c.value.includes("@story"));
+    let name = getNodeName(node);
+    if (node.type === "TSDeclareFunction" && node.id && node.id.name) {
+        name = node.id.name;
+    }
+    context.report({
+        node,
+        messageId: "missingStory",
+        data: { name },
+        suggest: [
+            {
+                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${ANNOTATION}`,
+                fix: (fixer) => fixer.insertTextBefore(target, `${ANNOTATION}\n`),
+            },
+        ],
+    });
 }
 /**
- * Check for @story annotation on function-like nodes.
+ * Report missing @story annotation on class methods
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-UNIFIED-CHECK
  * @req REQ-ANNOTATION-REQUIRED
+ * @param {Rule.RuleContext} context - ESLint rule context
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - MethodDefinition AST node
  */
-function checkStoryAnnotation(sourceCode, context, node, scope, exportPriority) {
-    if (!shouldCheckNode(node, scope, exportPriority)) {
-        return;
-    }
-    // Special handling for TSMethodSignature: allow annotation on the method itself
-    if (node.type === "TSMethodSignature") {
-        // If annotated on the method signature, skip
-        if (hasStoryAnnotation(sourceCode, node)) {
-            return;
-        }
-        // Otherwise, check on interface declaration
-        const intf = resolveTargetNode(sourceCode, node);
-        if (hasStoryAnnotation(sourceCode, intf)) {
-            return;
-        }
-        // Missing annotation: report on the interface declaration
-        context.report({
-            node: intf,
-            messageId: "missingStory",
-            fix(fixer) {
-                const indentLevel = intf.loc.start.column;
-                const indent = " ".repeat(indentLevel);
-                const insertPos = intf.range[0] - indentLevel;
-                return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}/** @story <story-file>.story.md */\n`);
-            },
-        });
-        return;
-    }
-    const target = resolveTargetNode(sourceCode, node);
-    if (hasStoryAnnotation(sourceCode, target)) {
+function reportMethod(context, sourceCode, node) {
+    if (hasStoryAnnotation(sourceCode, node)) {
         return;
     }
     context.report({
         node,
         messageId: "missingStory",
-        fix(fixer) {
-            const indentLevel = target.loc.start.column;
-            const indent = " ".repeat(indentLevel);
-            const insertPos = target.range[0] - indentLevel;
-            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}/** @story <story-file>.story.md */\n`);
-        },
+        data: { name: getNodeName(node) },
+        suggest: [
+            {
+                desc: `Add JSDoc @story annotation for function '${getNodeName(node)}', e.g., ${ANNOTATION}`,
+                fix: (fixer) => fixer.insertTextBefore(node, `${ANNOTATION}\n  `),
+            },
+        ],
     });
 }
-exports.default = {
+/**
+ * Check if this node is within scope and matches exportPriority
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ * @param {any} node - AST node to evaluate
+ * @param {string[]} scope - allowed node types
+ * @param {string} exportPriority - 'all' | 'exported' | 'non-exported'
+ * @returns {boolean} whether node should be processed
+ */
+function shouldProcessNode(node, scope, exportPriority) {
+    if (!scope.includes(node.type)) {
+        return false;
+    }
+    const exported = isExportedNode(node);
+    if (exportPriority === "exported" && !exported) {
+        return false;
+    }
+    if (exportPriority === "non-exported" && exported) {
+        return false;
+    }
+    return true;
+}
+const rule = {
     meta: {
         type: "problem",
         docs: {
-            description: "Require @story annotations on selected functions",
+            description: "Require @story annotations on functions",
             recommended: "error",
         },
-        fixable: "code",
+        hasSuggestions: true,
         messages: {
             missingStory: "Missing @story annotation (REQ-ANNOTATION-REQUIRED)",
         },
@@ -188,61 +210,69 @@ exports.default = {
                 properties: {
                     scope: {
                         type: "array",
-                        items: {
-                            enum: [
-                                "FunctionDeclaration",
-                                "FunctionExpression",
-                                "ArrowFunctionExpression",
-                                "MethodDefinition",
-                                "TSDeclareFunction",
-                                "TSMethodSignature",
-                            ],
-                        },
+                        items: { type: "string", enum: DEFAULT_SCOPE },
                         uniqueItems: true,
                     },
-                    exportPriority: {
-                        enum: ["all", "exported", "non-exported"],
-                    },
+                    exportPriority: { type: "string", enum: EXPORT_PRIORITY_VALUES },
                 },
                 additionalProperties: false,
             },
         ],
     },
+    /**
+     * Create the rule visitor functions for require-story-annotation.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-CREATE-HOOK - Provide create(context) hook for rule behavior
+     */
     create(context) {
         const sourceCode = context.getSourceCode();
-        const options = context.options[0] || {};
-        const scope = options.scope || [
-            "FunctionDeclaration",
-            "FunctionExpression",
-            "ArrowFunctionExpression",
-            "MethodDefinition",
-            "TSDeclareFunction",
-            "TSMethodSignature",
-        ];
-        const exportPriority = options.exportPriority || "all";
+        const opts = context.options[0] ||
+            {};
+        const scope = opts.scope || DEFAULT_SCOPE;
+        const exportPriority = opts.exportPriority || "all";
         return {
             FunctionDeclaration(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                let target = node;
+                if (node.parent &&
+                    (node.parent.type === "ExportNamedDeclaration" ||
+                        node.parent.type === "ExportDefaultDeclaration")) {
+                    target = node.parent;
+                }
+                reportMissing(context, sourceCode, node, target);
             },
             FunctionExpression(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                if (node.parent && node.parent.type === "MethodDefinition")
+                    return;
+                const target = resolveTargetNode(sourceCode, node);
+                reportMissing(context, sourceCode, node, target);
             },
             ArrowFunctionExpression(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                const target = resolveTargetNode(sourceCode, node);
+                reportMissing(context, sourceCode, node, target);
             },
-            MethodDefinition(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
-            },
-            // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-            // @req REQ-FUNCTION-DETECTION - Detect TS-specific function syntax
             TSDeclareFunction(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                reportMissing(context, sourceCode, node, node);
             },
-            // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-            // @req REQ-FUNCTION-DETECTION - Detect TS-specific function syntax
             TSMethodSignature(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                const target = resolveTargetNode(sourceCode, node);
+                reportMissing(context, sourceCode, node, target);
+            },
+            MethodDefinition(node) {
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                reportMethod(context, sourceCode, node);
             },
         };
     },
 };
+exports.default = rule;

package/lib/src/rules/valid-annotation-format.js

@@ -21,9 +21,20 @@ exports.default = {
         },
         schema: [],
     },
+    /**
+     * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+     * @req REQ-SYNTAX-VALIDATION - Ensure rule create function validates annotations syntax
+     * @req REQ-FORMAT-SPECIFICATION - Implement formatting checks per specification
+     */
     create(context) {
         const sourceCode = context.getSourceCode();
         return {
+            /**
+             * Program-level handler that inspects all comments for @story and @req tags
+             * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+             * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
+             * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
+             */
             Program() {
                 const comments = sourceCode.getAllComments() || [];
                 comments.forEach((comment) => {

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

@@ -19,6 +19,9 @@ const path_1 = __importDefault(require("path"));
  * Parses comment.value lines for @story annotation.
  * @param comment any JSDoc comment node
  * @returns story path or null if not found
+ *
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Extracts @story annotation from comment content
  */
 function extractStoryPath(comment) {
     const rawLines = comment.value.split(/\r?\n/);
@@ -34,14 +37,17 @@ function extractStoryPath(comment) {
 /**
  * Validate a @req annotation line against the extracted story content.
  * Performs path validation, file reading, caching, and requirement existence checks.
- * @param comment any JSDoc comment node
- * @param context ESLint rule context
- * @param line the @req annotation line
- * @param storyPath current story path
- * @param cwd current working directory
- * @param reqCache cache mapping story paths to sets of requirement IDs
+ *
+ * @param opts options bag
+ *
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PATH - Validates and protects against path traversal and absolute paths
+ * @req REQ-DEEP-CACHE - Caches parsed story files to avoid repeated IO
+ * @req REQ-DEEP-MATCH - Ensures referenced requirement IDs exist in the story file
+ * @req REQ-DEEP-PARSE - Parses story file content to find REQ- identifiers
  */
-function validateReqLine(comment, context, line, storyPath, cwd, reqCache) {
+function validateReqLine(opts) {
+    const { comment, context, line, storyPath, cwd, reqCache } = opts;
     const parts = line.split(/\s+/);
     const reqId = parts[1];
     if (!reqId || !storyPath) {
@@ -93,43 +99,62 @@ function validateReqLine(comment, context, line, storyPath, cwd, reqCache) {
  * Handle a single annotation line.
  * @story Updates the current story path when encountering an @story annotation
  * @req Validates the requirement reference against the current story content
- * @param line the trimmed annotation line
- * @param comment JSDoc comment node
- * @param context ESLint rule context
- * @param cwd current working directory
- * @param reqCache cache mapping story paths to sets of requirement IDs
- * @param storyPath current story path or null
- * @returns updated story path or null
+ *
+ * @param opts handler options
+ *
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Recognizes @story and @req annotation lines
+ * @req REQ-DEEP-MATCH - Delegates @req validation to validateReqLine
  */
-function handleAnnotationLine(line, comment, context, cwd, reqCache, storyPath) {
+function handleAnnotationLine(opts) {
+    const { line, comment, context, cwd, reqCache, storyPath } = opts;
     if (line.startsWith("@story")) {
         const newPath = extractStoryPath(comment);
         return newPath || storyPath;
     }
     else if (line.startsWith("@req")) {
-        validateReqLine(comment, context, line, storyPath, cwd, reqCache);
+        validateReqLine({ comment, context, line, storyPath, cwd, reqCache });
         return storyPath;
     }
     return storyPath;
 }
 /**
  * Handle JSDoc story and req annotations.
- * @param comment any JSDoc comment node
- * @param context ESLint rule context
- * @param cwd current working directory
- * @param reqCache cache mapping story paths to sets of requirement IDs
- * @param rawStoryPath the last extracted story path or null
- * @returns updated story path or null
+ *
+ * @param opts options for comment handling
+ *
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Parses comment blocks to extract annotation lines
+ * @req REQ-DEEP-MATCH - Uses handleAnnotationLine to validate @req entries
+ * @req REQ-DEEP-CACHE - Passes shared cache for parsed story files
  */
-function handleComment(comment, context, cwd, reqCache, rawStoryPath) {
+function handleComment(opts) {
+    const { comment, context, cwd, reqCache, rawStoryPath } = opts;
     let storyPath = rawStoryPath;
     const rawLines = comment.value.split(/\r?\n/);
     for (const rawLine of rawLines) {
         const line = rawLine.trim().replace(/^\*+\s*/, "");
-        storyPath = handleAnnotationLine(line, comment, context, cwd, reqCache, storyPath);
+        storyPath = handleAnnotationLine({
+            line,
+            comment,
+            context,
+            cwd,
+            reqCache,
+            storyPath,
+        });
     }
     return storyPath;
 }
+/**
+ * Create a Program listener that iterates comments and validates annotations.
+ *
+ * @param context ESLint rule context
+ * @returns Program visitor function
+ *
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-CACHE - Maintains a cache across comment processing
+ * @req REQ-DEEP-PATH - Resolves and protects story paths against traversal
+ */
 function programListener(context) {
     const sourceCode = context.getSourceCode();
     const cwd = process.cwd();
@@ -138,7 +163,13 @@ function programListener(context) {
     return function Program() {
         const comments = sourceCode.getAllComments() || [];
         comments.forEach((comment) => {
-            rawStoryPath = handleComment(comment, context, cwd, reqCache, rawStoryPath);
+            rawStoryPath = handleComment({
+                comment,
+                context,
+                cwd,
+                reqCache,
+                rawStoryPath,
+            });
         });
     };
 }
@@ -155,6 +186,15 @@ exports.default = {
         },
         schema: [],
     },
+    /**
+     * Rule create entrypoint that returns the Program visitor.
+     *
+     * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+     * @req REQ-DEEP-MATCH - Entrypoint orchestrates validation of @req annotations
+     * @req REQ-DEEP-PARSE - Uses parsing helpers to extract annotations and story paths
+     * @req REQ-DEEP-CACHE - Establishes cache used during validation
+     * @req REQ-DEEP-PATH - Ensures path validation is applied during checks
+     */
     create(context) {
         return { Program: programListener(context) };
     },