eslint-plugin-traceability 1.0.0

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * ESLint Traceability Plugin
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
+ */
+
+import requireStoryAnnotation from "./rules/require-story-annotation";
+import requireReqAnnotation from "./rules/require-req-annotation";
+import requireBranchAnnotation from "./rules/require-branch-annotation";
+import validAnnotationFormat from "./rules/valid-annotation-format";
+import validStoryReference from "./rules/valid-story-reference";
+import validReqReference from "./rules/valid-req-reference";
+
+export const rules = {
+  "require-story-annotation": requireStoryAnnotation,
+  "require-req-annotation": requireReqAnnotation,
+  "require-branch-annotation": requireBranchAnnotation,
+  "valid-annotation-format": validAnnotationFormat,
+  "valid-story-reference": validStoryReference,
+  "valid-req-reference": validReqReference,
+};
+
+export const configs = {
+  recommended: [
+    {
+      plugins: {
+        traceability: {},
+      },
+      rules: {
+        "traceability/require-story-annotation": "error",
+        "traceability/require-req-annotation": "error",
+        "traceability/require-branch-annotation": "error",
+        "traceability/valid-annotation-format": "error",
+        "traceability/valid-story-reference": "error",
+        "traceability/valid-req-reference": "error",
+      },
+    },
+  ],
+  strict: [
+    {
+      plugins: {
+        traceability: {},
+      },
+      rules: {
+        "traceability/require-story-annotation": "error",
+        "traceability/require-req-annotation": "error",
+        "traceability/require-branch-annotation": "error",
+        "traceability/valid-annotation-format": "error",
+        "traceability/valid-story-reference": "error",
+        "traceability/valid-req-reference": "error",
+      },
+    },
+  ],
+};
+
+export default { rules, configs };

package/src/maintenance/batch.ts

@@ -0,0 +1,29 @@
+import { updateAnnotationReferences } from "./update";
+import { detectStaleAnnotations } from "./detect";
+
+/**
+ * Batch update annotations and verify references
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-BATCH - Perform batch updates
+ * @req REQ-MAINT-VERIFY - Verify annotation references
+ */
+export function batchUpdateAnnotations(
+  codebasePath: string,
+  mappings: { oldPath: string; newPath: string }[],
+): number {
+  let totalUpdated = 0;
+  for (const { oldPath, newPath } of mappings) {
+    totalUpdated += updateAnnotationReferences(codebasePath, oldPath, newPath);
+  }
+  return totalUpdated;
+}
+
+/**
+ * Verify annotation references in codebase after maintenance operations
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-VERIFY - Verify annotation references
+ */
+export function verifyAnnotations(codebasePath: string): boolean {
+  const staleAnnotations = detectStaleAnnotations(codebasePath);
+  return staleAnnotations.length === 0;
+}

package/src/maintenance/detect.ts

@@ -0,0 +1,42 @@
+import * as fs from "fs";
+import * as path from "path";
+import { getAllFiles } from "./utils";
+
+/**
+ * Detect stale annotation references that point to moved or deleted story files
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-DETECT - Detect stale annotation references
+ */
+export function detectStaleAnnotations(codebasePath: string): string[] {
+  if (
+    !fs.existsSync(codebasePath) ||
+    !fs.statSync(codebasePath).isDirectory()
+  ) {
+    return [];
+  }
+
+  const cwd = process.cwd();
+  const baseDir = path.resolve(cwd, codebasePath);
+
+  const stale = new Set<string>();
+
+  const files = getAllFiles(codebasePath);
+  for (const file of files) {
+    const content = fs.readFileSync(file, "utf8");
+    const regex = /@story\s+([^\s]+)/g;
+    let match: RegExpExecArray | null;
+    while ((match = regex.exec(content)) !== null) {
+      const storyPath = match[1];
+      const storyProjectPath = path.resolve(cwd, storyPath);
+      const storyCodebasePath = path.resolve(baseDir, storyPath);
+      if (
+        !fs.existsSync(storyProjectPath) &&
+        !fs.existsSync(storyCodebasePath)
+      ) {
+        stale.add(storyPath);
+      }
+    }
+  }
+
+  return Array.from(stale);
+}

package/src/maintenance/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Maintenance Tools Module
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-DETECT
+ * @req REQ-MAINT-UPDATE
+ * @req REQ-MAINT-BATCH
+ * @req REQ-MAINT-VERIFY
+ * @req REQ-MAINT-REPORT
+ * @req REQ-MAINT-SAFE
+ */
+export { detectStaleAnnotations } from "./detect";
+export { updateAnnotationReferences } from "./update";
+export { batchUpdateAnnotations, verifyAnnotations } from "./batch";
+export { generateMaintenanceReport } from "./report";

package/src/maintenance/report.ts

@@ -0,0 +1,15 @@
+import { detectStaleAnnotations } from "./detect";
+
+/**
+ * Generate a report of maintenance operations performed
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Generate maintenance report
+ * @req REQ-MAINT-SAFE - Ensure operations are safe and reversible
+ */
+export function generateMaintenanceReport(codebasePath: string): string {
+  const staleAnnotations = detectStaleAnnotations(codebasePath);
+  if (staleAnnotations.length === 0) {
+    return "";
+  }
+  return staleAnnotations.join("\n");
+}

package/src/maintenance/update.ts

@@ -0,0 +1,40 @@
+import * as fs from "fs";
+import { getAllFiles } from "./utils";
+
+/**
+ * Update annotation references when story files are moved or renamed
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - Update annotation references
+ */
+export function updateAnnotationReferences(
+  codebasePath: string,
+  oldPath: string,
+  newPath: string,
+): number {
+  if (
+    !fs.existsSync(codebasePath) ||
+    !fs.statSync(codebasePath).isDirectory()
+  ) {
+    return 0;
+  }
+
+  let replacementCount = 0;
+  const escapedOldPath = oldPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`(@story\\s*)${escapedOldPath}`, "g");
+
+  const files = getAllFiles(codebasePath);
+  for (const fullPath of files) {
+    const stat = fs.statSync(fullPath);
+    if (!stat.isFile()) continue;
+    const content = fs.readFileSync(fullPath, "utf8");
+    const newContent = content.replace(regex, (match, p1) => {
+      replacementCount++;
+      return `${p1}${newPath}`;
+    });
+    if (newContent !== content) {
+      fs.writeFileSync(fullPath, newContent, "utf8");
+    }
+  }
+
+  return replacementCount;
+}

package/src/maintenance/utils.ts

@@ -0,0 +1,28 @@
+import * as fs from "fs";
+import * as path from "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
+ */
+export function getAllFiles(dir: string): string[] {
+  const fileList: string[] = [];
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return fileList;
+  }
+  function traverse(currentDir: string) {
+    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/src/rules/require-branch-annotation.ts

@@ -0,0 +1,114 @@
+/**
+ * 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
+ */
+export 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: any) {
+    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: any) {
+      // @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: string[] = [];
+        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: any) => c.value).join(" ");
+
+      const missingStory = !/@story\b/.test(text);
+      const missingReq = !/@req\b/.test(text);
+
+      if (missingStory) {
+        const reportObj: any = {
+          node,
+          messageId: "missingAnnotation",
+          data: { missing: "@story" },
+        };
+        if (node.type !== "CatchClause") {
+          if (node.type === "SwitchCase") {
+            const indent = " ".repeat(node.loc.start.column);
+            reportObj.fix = (fixer: any) =>
+              fixer.insertTextBefore(
+                node,
+                `// @story <story-file>.story.md\n${indent}`,
+              );
+          } else {
+            reportObj.fix = (fixer: any) =>
+              fixer.insertTextBefore(node, `// @story <story-file>.story.md\n`);
+          }
+        }
+        context.report(reportObj);
+      }
+      if (missingReq) {
+        const reportObj: any = {
+          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: any) =>
+              fixer.insertTextBefore(node, `// @req <REQ-ID>\n${indent}`);
+          } else {
+            reportObj.fix = (fixer: any) =>
+              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,
+    };
+  },
+} as any;

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

@@ -0,0 +1,36 @@
+/**
+ * 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
+ */
+export default {
+  meta: {
+    type: "problem",
+    fixable: "code",
+    docs: {
+      description: "Require @req annotations on functions",
+      recommended: "error",
+    },
+    messages: {
+      missingReq: "Missing @req annotation",
+    },
+    schema: [],
+  },
+  create(context: any) {
+    const sourceCode = context.getSourceCode();
+    return {
+      FunctionDeclaration(node: any) {
+        const jsdoc = sourceCode.getJSDocComment(node);
+        if (!jsdoc || !jsdoc.value.includes("@req")) {
+          context.report({
+            node,
+            messageId: "missingReq",
+            fix(fixer: any) {
+              return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
+            },
+          });
+        }
+      },
+    };
+  },
+} as any;

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

@@ -0,0 +1,52 @@
+/**
+ * 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
+ */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require @story annotations on functions",
+      recommended: "error",
+    },
+    fixable: "code",
+    messages: {
+      missingStory: "Missing @story annotation",
+    },
+    schema: [],
+  },
+  create(context: any) {
+    const sourceCode = context.getSourceCode();
+    return {
+      FunctionDeclaration(node: any) {
+        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: any) =>
+            comment.value.includes("@story"),
+          );
+        }
+        if (!hasStory) {
+          context.report({
+            node,
+            messageId: "missingStory",
+            fix(fixer: any) {
+              return fixer.insertTextBefore(
+                node,
+                "/** @story <story-file>.story.md */\n",
+              );
+            },
+          });
+        }
+      },
+    };
+  },
+} as any;

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

@@ -0,0 +1,62 @@
+/**
+ * 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
+ */
+export 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: any) {
+    const sourceCode = context.getSourceCode();
+    return {
+      Program() {
+        const comments = sourceCode.getAllComments() || [];
+        comments.forEach((comment: any) => {
+          const lines = comment.value
+            .split(/\r?\n/)
+            .map((l: string) => l.replace(/^[^@]*/, "").trim());
+          lines.forEach((line: string) => {
+            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 as any,
+                  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 as any,
+                  messageId: "invalidReqFormat",
+                });
+              }
+            }
+          });
+        });
+      },
+    };
+  },
+} as any;

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

@@ -0,0 +1,114 @@
+/* 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
+ */
+import fs from "fs";
+import path from "path";
+import type { Rule } from "eslint";
+
+export 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<string, Set<string>>();
+
+    let rawStoryPath: string | null = 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.isAbsolute(rawStoryPath)
+              ) {
+                context.report({
+                  node: comment as any,
+                  messageId: "invalidPath",
+                  data: { storyPath: rawStoryPath },
+                });
+                return;
+              }
+
+              const resolvedStoryPath = path.resolve(cwd, rawStoryPath);
+              if (
+                !resolvedStoryPath.startsWith(cwd + path.sep) &&
+                resolvedStoryPath !== cwd
+              ) {
+                context.report({
+                  node: comment as any,
+                  messageId: "invalidPath",
+                  data: { storyPath: rawStoryPath },
+                });
+                return;
+              }
+
+              // Load and parse story file if not cached
+              if (!reqCache.has(resolvedStoryPath)) {
+                try {
+                  const content = fs.readFileSync(resolvedStoryPath, "utf8");
+                  const found = new Set<string>();
+                  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 as any,
+                  messageId: "reqMissing",
+                  data: { reqId, storyPath: rawStoryPath },
+                });
+              }
+            }
+          });
+        });
+      },
+    };
+  },
+} as Rule.RuleModule;