eslint-plugin-traceability 1.6.4 → 1.6.5

package/lib/src/maintenance/detect.js

@@ -87,12 +87,12 @@ function processFileForStaleAnnotations(file, workspaceRoot, cwd, stale) {
 }
 /**
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - Handle individual @story matches within a file
+ * @req REQ-MAINT-DETECT REQ-SECURITY-VALIDATION - 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)) {
+    // @req REQ-MAINT-DETECT REQ-SECURITY-VALIDATION - Skip traversal/absolute-unsafe or invalid-extension story paths before any filesystem or boundary checks
+    if ((0, storyReferenceUtils_1.isUnsafeStoryPath)(storyPath)) {
         return;
     }
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md

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

@@ -13,28 +13,17 @@ 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.
+     *
+     * Developers who need to troubleshoot this handler may temporarily add
+     * console.debug statements here, but by default no debug logging runs so that
+     * file paths and other details are not leaked during normal linting.
+     *
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
      * @req REQ-ANNOTATION-REQUIRED - Report missing @story on function declarations
      */
     function handleFunctionDeclaration(node) {
-        /**
-         * Debug logging for visitor entry
-         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-         * @req REQ-DEBUG-LOG - Provide debug logging for visitor entry
-         */
-        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

@@ -64,24 +64,19 @@ const rule = {
         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.
+         * Optional debug logging for troubleshooting this rule.
+         * Developers can temporarily uncomment the block below to log when the rule
+         * is activated for a given file during ESLint runs.
          *
          * @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
-         */
-        if (debugEnabled) {
-            console.debug("require-story-annotation:create", typeof context.getFilename === "function"
-                ? context.getFilename()
-                : "<unknown>");
-        }
+        // 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/tests/maintenance/detect-isolated.test.js

@@ -38,10 +38,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
  */
-const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const detect_1 = require("../../src/maintenance/detect");
+const fs = require("fs");
 describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
     it("[REQ-MAINT-DETECT] returns empty array when directory does not exist", () => {
         const result = (0, detect_1.detectStaleAnnotations)("non-existent-dir");
@@ -107,4 +107,71 @@ describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)",
             }
         }
     });
+    /**
+     * [REQ-MAINT-DETECT]
+     * Ensure detectStaleAnnotations performs security validation for unsafe
+     * and invalid-extension story paths and does not perform filesystem checks
+     * for malicious @story paths that escape the workspace
+     * (Story 009.0-DEV-MAINTENANCE-TOOLS).
+     */
+    it("[REQ-MAINT-DETECT] performs security validation for unsafe and invalid-extension story paths without stat'ing outside workspace", () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-workspace-"));
+        const maliciousRelative = "../outside-project.story.md";
+        const maliciousAbsolute = "/etc/passwd.story.md";
+        const traversalInside = "nested/../inside.story.md";
+        const invalidExtension = "invalid.txt";
+        const filePath = path.join(tmpDir, "file.ts");
+        const content = `
+/**
+ * @story ${maliciousRelative}
+ * @story ${maliciousAbsolute}
+ * @story ${traversalInside}
+ * @story ${invalidExtension}
+ * @story legitimate.story.md
+ */
+`;
+        fs.writeFileSync(filePath, content, "utf8");
+        const existsCalls = [];
+        const originalExistsSync = fs.existsSync;
+        const existsSpy = jest
+            .spyOn(fs, "existsSync")
+            .mockImplementation((p) => {
+            const strPath = typeof p === "string" ? p : p.toString();
+            existsCalls.push(strPath);
+            return originalExistsSync(p);
+        });
+        try {
+            (0, detect_1.detectStaleAnnotations)(tmpDir);
+            const allPathsChecked = [...existsCalls];
+            // Ensure no raw malicious values were checked
+            expect(allPathsChecked).not.toContain(maliciousRelative);
+            expect(allPathsChecked).not.toContain(maliciousAbsolute);
+            expect(allPathsChecked).not.toContain(invalidExtension);
+            // Also ensure no resolved variants of these paths were checked
+            const resolvedRelative = path.resolve(tmpDir, maliciousRelative);
+            const resolvedAbsolute = path.resolve(maliciousAbsolute);
+            const resolvedInvalid = path.resolve(tmpDir, invalidExtension);
+            expect(allPathsChecked).not.toContain(resolvedRelative);
+            expect(allPathsChecked).not.toContain(resolvedAbsolute);
+            expect(allPathsChecked).not.toContain(resolvedInvalid);
+            expect(allPathsChecked.some((p) => p.includes("outside-project.story.md"))).toBe(false);
+            expect(allPathsChecked.some((p) => p.includes("passwd.story.md"))).toBe(false);
+            expect(allPathsChecked.some((p) => p.includes("invalid.txt"))).toBe(false);
+            // traversalInside normalizes within workspace and should be checked
+            const resolvedTraversalInside = path.resolve(tmpDir, traversalInside);
+            expect(allPathsChecked).toContain(resolvedTraversalInside);
+            // legitimate in-workspace .story.md path should also be checked
+            const resolvedLegit = path.resolve(tmpDir, "legitimate.story.md");
+            expect(allPathsChecked).toContain(resolvedLegit);
+        }
+        finally {
+            existsSpy.mockRestore();
+            try {
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+            }
+            catch {
+                // ignore cleanup errors
+            }
+        }
+    });
 });

package/lib/tests/maintenance/report.test.js

@@ -58,10 +58,10 @@ describe("generateMaintenanceReport (Story 009.0-DEV-MAINTENANCE-TOOLS)", () =>
     it("[REQ-MAINT-REPORT] should report stale story annotation", () => {
         const filePath = path.join(tmpDir, "stub.md");
         const content = `/**
- * @story non-existent.md
+ * @story non-existent.story.md
  */`;
         fs.writeFileSync(filePath, content);
         const report = (0, report_1.generateMaintenanceReport)(tmpDir);
-        expect(report).toContain("non-existent.md");
+        expect(report).toContain("non-existent.story.md");
     });
 });

package/package.json

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