eslint-plugin-traceability 1.4.2 → 1.4.3

package/lib/src/maintenance/update.js

@@ -50,15 +50,36 @@ function updateAnnotationReferences(codebasePath, oldPath, newPath) {
     const escapedOldPath = oldPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const regex = new RegExp(`(@story\\s*)${escapedOldPath}`, "g");
     const files = (0, utils_1.getAllFiles)(codebasePath);
+    /**
+     * Iterate over all files and replace annotation references
+     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+     * @req REQ-MAINT-UPDATE
+     */
     for (const fullPath of files) {
         const stat = fs.statSync(fullPath);
+        /**
+         * Skip non-files in iteration
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UPDATE
+         */
         if (!stat.isFile())
             continue;
         const content = fs.readFileSync(fullPath, "utf8");
-        const newContent = content.replace(regex, (match, p1) => {
+        const newContent = content.replace(regex, 
+        /**
+         * Replacement callback to update annotation references
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UPDATE
+         */
+        (match, p1) => {
             replacementCount++;
             return `${p1}${newPath}`;
         });
+        /**
+         * Write file only if content changed
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UPDATE
+         */
         if (newContent !== content) {
             fs.writeFileSync(fullPath, newContent, "utf8");
         }

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

@@ -242,6 +242,12 @@ const rule = {
                 }
                 reportMissing(context, sourceCode, node, target);
             },
+            /**
+             * Handle FunctionExpression nodes
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-ANNOTATION-REQUIRED
+             * @param {any} node - FunctionExpression AST node
+             */
             FunctionExpression(node) {
                 if (!shouldProcessNode(node, scope, exportPriority))
                     return;
@@ -250,23 +256,47 @@ const rule = {
                 const target = resolveTargetNode(sourceCode, node);
                 reportMissing(context, sourceCode, node, target);
             },
+            /**
+             * Handle ArrowFunctionExpression nodes
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-ANNOTATION-REQUIRED
+             * @param {any} node - ArrowFunctionExpression AST node
+             */
             ArrowFunctionExpression(node) {
                 if (!shouldProcessNode(node, scope, exportPriority))
                     return;
                 const target = resolveTargetNode(sourceCode, node);
                 reportMissing(context, sourceCode, node, target);
             },
+            /**
+             * Handle TSDeclareFunction nodes
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-ANNOTATION-REQUIRED
+             * @param {any} node - TSDeclareFunction AST node
+             */
             TSDeclareFunction(node) {
                 if (!shouldProcessNode(node, scope, exportPriority))
                     return;
                 reportMissing(context, sourceCode, node, node);
             },
+            /**
+             * Handle TSMethodSignature nodes
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-ANNOTATION-REQUIRED
+             * @param {any} node - TSMethodSignature AST node
+             */
             TSMethodSignature(node) {
                 if (!shouldProcessNode(node, scope, exportPriority))
                     return;
                 const target = resolveTargetNode(sourceCode, node);
                 reportMissing(context, sourceCode, node, target);
             },
+            /**
+             * Handle MethodDefinition nodes
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-ANNOTATION-REQUIRED
+             * @param {any} node - MethodDefinition AST node
+             */
             MethodDefinition(node) {
                 if (!shouldProcessNode(node, scope, exportPriority))
                     return;

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

@@ -32,10 +32,19 @@ exports.DEFAULT_BRANCH_TYPES = [
 function validateBranchTypes(context) {
     const options = context.options[0] || {};
     if (Array.isArray(options.branchTypes)) {
+        // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+        // @req REQ-TRACEABILITY-FILTER-CALLBACK - Trace filter callback for invalid branch type detection
         const invalidTypes = options.branchTypes.filter((t) => !exports.DEFAULT_BRANCH_TYPES.includes(t));
         if (invalidTypes.length > 0) {
+            /**
+             * Program listener produced when configuration is invalid.
+             * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+             * @req REQ-TRACEABILITY-PROGRAM-LISTENER - Trace Program listener reporting invalid config values
+             */
             return {
                 Program(node) {
+                    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+                    // @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace reporting for each invalid type
                     invalidTypes.forEach((t) => {
                         context.report({
                             node,
@@ -61,6 +70,8 @@ function gatherBranchCommentText(sourceCode, node) {
         const startLine = node.loc.start.line;
         let i = startLine - PRE_COMMENT_OFFSET;
         const comments = [];
+        // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+        // @req REQ-TRACEABILITY-WHILE - Trace while loop that collects preceding comments for SwitchCase
         while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
             comments.unshift(lines[i].trim());
             i--;
@@ -68,6 +79,8 @@ function gatherBranchCommentText(sourceCode, node) {
         return comments.join(" ");
     }
     const comments = sourceCode.getCommentsBefore(node) || [];
+    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+    // @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
     return comments.map((c) => c.value).join(" ");
 }
 /**
@@ -82,7 +95,10 @@ function reportMissingStory(context, node, options) {
             node,
             messageId: "missingAnnotation",
             data: { missing: "@story" },
-            fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`),
+            fix: 
+            // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+            // @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer arrow function used to insert missing @story
+            (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`),
         });
         storyFixCountRef.count++;
     }
@@ -106,7 +122,10 @@ function reportMissingReq(context, node, options) {
             node,
             messageId: "missingAnnotation",
             data: { missing: "@req" },
-            fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`),
+            fix: 
+            // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+            // @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer arrow function used to insert missing @req
+            (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`),
         });
     }
     else {
@@ -144,5 +163,10 @@ function reportMissingAnnotations(context, node, storyFixCountRef) {
             args: [context, node, { indent, insertPos, missingStory }],
         },
     ];
-    actions.forEach(({ missing, fn, args }) => missing && fn(...args));
+    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+    // @req REQ-TRACEABILITY-ACTIONS-FOREACH - Trace processing of actions array to report missing annotations
+    actions.forEach(({ missing, fn, args }) => 
+    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+    // @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace callback handling for each action item
+    missing && fn(...args));
 }

package/lib/tests/maintenance/detect-isolated.test.js

@@ -87,11 +87,24 @@ describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)",
 `;
         fs.writeFileSync(filePath, content, "utf8");
         // Remove read permission
-        fs.chmodSync(dir, 0o000);
-        expect(() => (0, detect_1.detectStaleAnnotations)(tmpDir2)).toThrow();
-        // Restore permissions
-        fs.chmodSync(dir, 0o700);
-        // Cleanup temporary directory
-        fs.rmSync(tmpDir2, { recursive: true, force: true });
+        try {
+            fs.chmodSync(dir, 0o000);
+            expect(() => (0, detect_1.detectStaleAnnotations)(tmpDir2)).toThrow();
+        }
+        finally {
+            // Restore permissions and cleanup temporary directory, ignoring errors during cleanup
+            try {
+                fs.chmodSync(dir, 0o700);
+            }
+            catch {
+                // ignore
+            }
+            try {
+                fs.rmSync(tmpDir2, { recursive: true, force: true });
+            }
+            catch {
+                // ignore
+            }
+        }
     });
 });

package/package.json

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