eslint-plugin-traceability 1.0.0

package/lib/src/maintenance/utils.js

@@ -0,0 +1,64 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAllFiles = getAllFiles;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Recursively retrieve all files in a directory.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UTILS - Extract common file traversal logic for maintenance tools
+ */
+function getAllFiles(dir) {
+    const fileList = [];
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+        return fileList;
+    }
+    function traverse(currentDir) {
+        const entries = fs.readdirSync(currentDir);
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                traverse(fullPath);
+            }
+            else if (stat.isFile()) {
+                fileList.push(fullPath);
+            }
+        }
+    }
+    traverse(dir);
+    return fileList;
+}

package/lib/src/rules/require-branch-annotation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Rule to enforce @story and @req annotations on significant code branches
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
+ */
+declare const _default: any;
+export default _default;

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

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Rule to enforce @story and @req annotations on significant code branches
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
+ */
+exports.default = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require @story and @req annotations on code branches",
+            recommended: "error",
+        },
+        fixable: "code",
+        messages: {
+            missingAnnotation: "Missing {{missing}} annotation on code branch",
+        },
+        schema: [],
+    },
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        /**
+         * Helper to check a branch AST node for traceability annotations.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
+         */
+        function checkBranch(node) {
+            // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+            // @req REQ-BRANCH-DETECTION - Skip default switch cases during annotation checks
+            // skip default cases in switch
+            if (node.type === "SwitchCase" && node.test == null) {
+                return;
+            }
+            // collect comments before node
+            let comments = sourceCode.getCommentsBefore(node) || [];
+            // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+            // @req REQ-BRANCH-DETECTION - Fallback scanning for SwitchCase when leading comments are absent
+            // fallback scanning for SwitchCase if no leading comment nodes
+            /* istanbul ignore if */
+            if (node.type === "SwitchCase" && comments.length === 0) {
+                const lines = sourceCode.lines;
+                const startLine = node.loc.start.line;
+                let i = startLine - 1;
+                const fallbackComments = [];
+                while (i > 0) {
+                    const lineText = lines[i - 1];
+                    if (/^\s*(\/\/|\/\*)/.test(lineText)) {
+                        fallbackComments.unshift(lineText.trim());
+                        i--;
+                    }
+                    else if (/^\s*$/.test(lineText)) {
+                        break;
+                    }
+                    else {
+                        break;
+                    }
+                }
+                comments = fallbackComments.map((text) => ({ value: text }));
+            }
+            const text = comments.map((c) => c.value).join(" ");
+            const missingStory = !/@story\b/.test(text);
+            const missingReq = !/@req\b/.test(text);
+            if (missingStory) {
+                const reportObj = {
+                    node,
+                    messageId: "missingAnnotation",
+                    data: { missing: "@story" },
+                };
+                if (node.type !== "CatchClause") {
+                    if (node.type === "SwitchCase") {
+                        const indent = " ".repeat(node.loc.start.column);
+                        reportObj.fix = (fixer) => fixer.insertTextBefore(node, `// @story <story-file>.story.md\n${indent}`);
+                    }
+                    else {
+                        reportObj.fix = (fixer) => fixer.insertTextBefore(node, `// @story <story-file>.story.md\n`);
+                    }
+                }
+                context.report(reportObj);
+            }
+            if (missingReq) {
+                const reportObj = {
+                    node,
+                    messageId: "missingAnnotation",
+                    data: { missing: "@req" },
+                };
+                if (!missingStory && node.type !== "CatchClause") {
+                    if (node.type === "SwitchCase") {
+                        const indent = " ".repeat(node.loc.start.column);
+                        reportObj.fix = (fixer) => fixer.insertTextBefore(node, `// @req <REQ-ID>\n${indent}`);
+                    }
+                    else {
+                        reportObj.fix = (fixer) => fixer.insertTextBefore(node, `// @req <REQ-ID>\n`);
+                    }
+                }
+                context.report(reportObj);
+            }
+        }
+        return {
+            IfStatement: checkBranch,
+            SwitchCase: checkBranch,
+            TryStatement: checkBranch,
+            CatchClause: checkBranch,
+            ForStatement: checkBranch,
+            ForOfStatement: checkBranch,
+            ForInStatement: checkBranch,
+            WhileStatement: checkBranch,
+            DoWhileStatement: checkBranch,
+        };
+    },
+};

package/lib/src/rules/require-req-annotation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Rule to enforce @req annotation on functions
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
+ */
+declare const _default: any;
+export default _default;

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Rule to enforce @req annotation on functions
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
+ */
+exports.default = {
+    meta: {
+        type: "problem",
+        fixable: "code",
+        docs: {
+            description: "Require @req annotations on functions",
+            recommended: "error",
+        },
+        messages: {
+            missingReq: "Missing @req annotation",
+        },
+        schema: [],
+    },
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        return {
+            FunctionDeclaration(node) {
+                const jsdoc = sourceCode.getJSDocComment(node);
+                if (!jsdoc || !jsdoc.value.includes("@req")) {
+                    context.report({
+                        node,
+                        messageId: "missingReq",
+                        fix(fixer) {
+                            return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
+                        },
+                    });
+                }
+            },
+        };
+    },
+};

package/lib/src/rules/require-story-annotation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Rule to enforce @story annotation on functions
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Require @story annotation on functions
+ */
+declare const _default: any;
+export default _default;

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Rule to enforce @story annotation on functions
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Require @story annotation on functions
+ */
+exports.default = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require @story annotations on functions",
+            recommended: "error",
+        },
+        fixable: "code",
+        messages: {
+            missingStory: "Missing @story annotation",
+        },
+        schema: [],
+    },
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        return {
+            FunctionDeclaration(node) {
+                const jsdoc = sourceCode.getJSDocComment(node);
+                let hasStory = false;
+                // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+                // @req REQ-JSDOC-PARSING - Detect JSDoc @story annotation presence
+                if (jsdoc && jsdoc.value.includes("@story")) {
+                    hasStory = true;
+                    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+                    // @req REQ-JSDOC-PARSING - Fallback to loading comments before node for @story annotation detection
+                }
+                else {
+                    const commentsBefore = sourceCode.getCommentsBefore(node) || [];
+                    hasStory = commentsBefore.some((comment) => comment.value.includes("@story"));
+                }
+                if (!hasStory) {
+                    context.report({
+                        node,
+                        messageId: "missingStory",
+                        fix(fixer) {
+                            return fixer.insertTextBefore(node, "/** @story <story-file>.story.md */\n");
+                        },
+                    });
+                }
+            },
+        };
+    },
+};

package/lib/src/rules/valid-annotation-format.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Rule to validate @story and @req annotation format and syntax
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @req REQ-FORMAT-SPECIFICATION - Define clear format rules for @story and @req annotations
+ * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
+ * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
+ * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
+ */
+declare const _default: any;
+export default _default;

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

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Rule to validate @story and @req annotation format and syntax
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @req REQ-FORMAT-SPECIFICATION - Define clear format rules for @story and @req annotations
+ * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
+ * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
+ * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
+ */
+exports.default = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Validate format and syntax of @story and @req annotations",
+            recommended: "error",
+        },
+        messages: {
+            invalidStoryFormat: "Invalid @story annotation format",
+            invalidReqFormat: "Invalid @req annotation format",
+        },
+        schema: [],
+    },
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        return {
+            Program() {
+                const comments = sourceCode.getAllComments() || [];
+                comments.forEach((comment) => {
+                    const lines = comment.value
+                        .split(/\r?\n/)
+                        .map((l) => l.replace(/^[^@]*/, "").trim());
+                    lines.forEach((line) => {
+                        if (line.startsWith("@story")) {
+                            const parts = line.split(/\s+/);
+                            const storyPath = parts[1];
+                            if (!storyPath ||
+                                !/^docs\/stories\/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$/.test(storyPath)) {
+                                context.report({
+                                    node: comment,
+                                    messageId: "invalidStoryFormat",
+                                });
+                            }
+                        }
+                        if (line.startsWith("@req")) {
+                            const parts = line.split(/\s+/);
+                            const reqId = parts[1];
+                            if (!reqId || !/^REQ-[A-Z0-9-]+$/.test(reqId)) {
+                                context.report({
+                                    node: comment,
+                                    messageId: "invalidReqFormat",
+                                });
+                            }
+                        }
+                    });
+                });
+            },
+        };
+    },
+};

package/lib/src/rules/valid-req-reference.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const _default: Rule.RuleModule;
+export default _default;

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

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-env node */
+/**
+ * Rule to validate @req annotation references refer to existing requirements in story files
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Parse story files to extract requirement identifiers
+ * @req REQ-DEEP-MATCH - Validate @req references against story file content
+ * @req REQ-DEEP-CACHE - Cache parsed story content for performance
+ * @req REQ-DEEP-PATH - Protect against path traversal in story paths
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.default = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Validate that @req annotations reference existing requirements in referenced story files",
+            recommended: "error",
+        },
+        messages: {
+            reqMissing: "Requirement '{{reqId}}' not found in '{{storyPath}}'",
+            invalidPath: "Invalid story path '{{storyPath}}'",
+        },
+        schema: [],
+    },
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        const cwd = process.cwd();
+        // Cache for resolved story file paths to parsed set of requirement IDs
+        const reqCache = new Map();
+        let rawStoryPath = null;
+        return {
+            Program() {
+                const comments = sourceCode.getAllComments() || [];
+                comments.forEach((comment) => {
+                    const rawLines = comment.value.split(/\r?\n/);
+                    const lines = rawLines.map((rawLine) => rawLine.trim().replace(/^\*+\s*/, ""));
+                    lines.forEach((line) => {
+                        if (line.startsWith("@story")) {
+                            const parts = line.split(/\s+/);
+                            rawStoryPath = parts[1] || null;
+                        }
+                        if (line.startsWith("@req")) {
+                            const parts = line.split(/\s+/);
+                            const reqId = parts[1];
+                            if (!reqId || !rawStoryPath) {
+                                return;
+                            }
+                            // Protect against path traversal and absolute paths
+                            if (rawStoryPath.includes("..") ||
+                                path_1.default.isAbsolute(rawStoryPath)) {
+                                context.report({
+                                    node: comment,
+                                    messageId: "invalidPath",
+                                    data: { storyPath: rawStoryPath },
+                                });
+                                return;
+                            }
+                            const resolvedStoryPath = path_1.default.resolve(cwd, rawStoryPath);
+                            if (!resolvedStoryPath.startsWith(cwd + path_1.default.sep) &&
+                                resolvedStoryPath !== cwd) {
+                                context.report({
+                                    node: comment,
+                                    messageId: "invalidPath",
+                                    data: { storyPath: rawStoryPath },
+                                });
+                                return;
+                            }
+                            // Load and parse story file if not cached
+                            if (!reqCache.has(resolvedStoryPath)) {
+                                try {
+                                    const content = fs_1.default.readFileSync(resolvedStoryPath, "utf8");
+                                    const found = new Set();
+                                    const regex = /REQ-[A-Z0-9-]+/g;
+                                    let match;
+                                    while ((match = regex.exec(content)) !== null) {
+                                        found.add(match[0]);
+                                    }
+                                    reqCache.set(resolvedStoryPath, found);
+                                }
+                                catch {
+                                    // Unable to read file, treat as no requirements
+                                    reqCache.set(resolvedStoryPath, new Set());
+                                }
+                            }
+                            const reqSet = reqCache.get(resolvedStoryPath);
+                            if (!reqSet.has(reqId)) {
+                                context.report({
+                                    node: comment,
+                                    messageId: "reqMissing",
+                                    data: { reqId, storyPath: rawStoryPath },
+                                });
+                            }
+                        }
+                    });
+                });
+            },
+        };
+    },
+};

package/lib/src/rules/valid-story-reference.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const _default: Rule.RuleModule;
+export default _default;

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

@@ -0,0 +1,168 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-env node */
+/**
+ * Rule to validate @story annotation references refer to existing story files
+ * @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
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const defaultStoryDirs = ["docs/stories", "stories"];
+const fileExistCache = new Map();
+/**
+ * Build possible file paths for a given storyPath.
+ * @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
+ */
+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;
+}
+/**
+ * Validate a single @story annotation line.
+ * @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;
+    }
+    // Absolute path check
+    if (path_1.default.isAbsolute(storyPath)) {
+        if (!allowAbsolute) {
+            context.report({
+                node: commentNode,
+                messageId: "invalidPath",
+                data: { path: storyPath },
+            });
+        }
+        return;
+    }
+    // Path traversal prevention
+    if (storyPath.includes("..")) {
+        const normalized = path_1.default.normalize(storyPath);
+        const full = path_1.default.resolve(cwd, normalized);
+        if (!full.startsWith(cwd + path_1.default.sep)) {
+            context.report({
+                node: commentNode,
+                messageId: "invalidPath",
+                data: { path: storyPath },
+            });
+            return;
+        }
+    }
+    // Extension check
+    if (requireExt && !storyPath.endsWith(".story.md")) {
+        context.report({
+            node: commentNode,
+            messageId: "invalidExtension",
+            data: { path: storyPath },
+        });
+        return;
+    }
+    // Build candidate paths and check existence
+    const candidates = buildCandidates(storyPath, cwd, storyDirs);
+    if (!existsAny(candidates)) {
+        context.report({
+            node: commentNode,
+            messageId: "fileMissing",
+            data: { path: storyPath },
+        });
+    }
+}
+/**
+ * Handle a single comment node by processing its lines.
+ * @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) {
+    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);
+        }
+    }
+}
+exports.default = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Validate that @story annotations reference existing .story.md files",
+            recommended: "error",
+        },
+        messages: {
+            fileMissing: "Story file '{{path}}' not found",
+            invalidExtension: "Invalid story file extension for '{{path}}', expected '.story.md'",
+            invalidPath: "Invalid story path '{{path}}'",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    storyDirectories: {
+                        type: "array",
+                        items: { type: "string" },
+                    },
+                    allowAbsolutePaths: { type: "boolean" },
+                    requireStoryExtension: { type: "boolean" },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    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() {
+                const comments = sourceCode.getAllComments() || [];
+                for (const comment of comments) {
+                    handleComment(comment, context, sourceCode, cwd, storyDirs, allowAbsolute, requireExt);
+                }
+            },
+        };
+    },
+};

package/lib/tests/basic.test.d.ts

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