eslint-plugin-traceability 1.1.0 → 1.1.2

package/eslint.config.js

@@ -1,146 +0,0 @@
-/**
- * ESLint flat config for Traceability Plugin
- * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
- * @req REQ-FLAT-CONFIG - Setup ESLint v9 flat config for plugin usage
- */
-
-const typescriptParser = require("@typescript-eslint/parser");
-const js = require("@eslint/js");
-
-// Try to load the plugin, but handle case where it doesn't exist yet
-let plugin;
-try {
-  plugin = require("./lib/index.js");
-} catch {
-  console.warn("Plugin not built yet, skipping traceability rules");
-  plugin = {};
-}
-
-module.exports = [
-  js.configs.recommended,
-  {
-    // Node.js config files
-    files: ["*.config.js", "*.config.mjs", "jest.config.js"],
-    languageOptions: {
-      ecmaVersion: 2022,
-      sourceType: "commonjs",
-      globals: {
-        require: "readonly",
-        module: "readonly",
-        exports: "readonly",
-        __dirname: "readonly",
-        __filename: "readonly",
-        console: "readonly",
-        process: "readonly",
-      },
-    },
-  },
-  {
-    files: ["cli-integration.js"],
-    languageOptions: {
-      ecmaVersion: 2022,
-      sourceType: "script",
-      globals: {
-        require: "readonly",
-        module: "readonly",
-        exports: "readonly",
-        __dirname: "readonly",
-        __filename: "readonly",
-        console: "readonly",
-        process: "readonly",
-      },
-    },
-    plugins: { ...(plugin.rules ? { traceability: plugin } : {}) },
-    rules: { complexity: "error" },
-  },
-  {
-    files: ["**/*.ts", "**/*.tsx"],
-    languageOptions: {
-      parser: typescriptParser,
-      parserOptions: {
-        project: "./tsconfig.json",
-        tsconfigRootDir: __dirname,
-        ecmaVersion: 2022,
-        sourceType: "module",
-      },
-      globals: {
-        process: "readonly",
-      },
-    },
-    plugins: {
-      ...(plugin.rules ? { traceability: plugin } : {}),
-    },
-    rules: {
-      complexity: "error",
-      // Enforce maximum lines per function for maintainability
-      "max-lines-per-function": ["error", { max: 80, skipBlankLines: true, skipComments: true }],
-      // Enforce maximum lines per file for maintainability
-      "max-lines": ["error", { max: 350, skipBlankLines: true, skipComments: true }],
-    },
-  },
-  {
-    files: ["**/*.js", "**/*.jsx"],
-    languageOptions: {
-      ecmaVersion: 2022,
-      sourceType: "module",
-    },
-    plugins: {
-      ...(plugin.rules ? { traceability: plugin } : {}),
-    },
-    rules: {
-      complexity: "error",
-      // Enforce maximum lines per function for maintainability
-      "max-lines-per-function": ["error", { max: 80, skipBlankLines: true, skipComments: true }],
-      // Enforce maximum lines per file for maintainability
-      "max-lines": ["error", { max: 350, skipBlankLines: true, skipComments: true }],
-    },
-  },
-  {
-    files: ["src/rules/**/*.ts"],
-    languageOptions: {
-      globals: {
-        process: "readonly",
-      },
-    },
-  },
-  {
-    // Test files
-    files: [
-      "**/*.test.{js,ts,tsx}",
-      "**/__tests__/**/*.{js,ts,tsx}",
-      "**/tests/**/*.{js,ts,tsx}",
-    ],
-    languageOptions: {
-      globals: {
-        describe: "readonly",
-        it: "readonly",
-        test: "readonly",
-        expect: "readonly",
-        beforeEach: "readonly",
-        afterEach: "readonly",
-        beforeAll: "readonly",
-        afterAll: "readonly",
-        jest: "readonly",
-        require: "readonly",
-        __dirname: "readonly",
-      },
-    },
-    rules: {
-      "max-lines-per-function": "off",
-      "max-lines": "off",
-    },
-  },
-  {
-    // Ignore build output and node_modules
-    ignores: [
-      "lib/**",
-      "node_modules/**",
-      "coverage/**",
-      ".cursor/**",
-      "**/.cursor/**",
-      ".voder/**",
-      "docs/**",
-      "*.md",
-    ],
-  },
-];

package/jest.config.js

@@ -1,21 +0,0 @@
-/****
- * Jest configuration for ESLint Traceability Plugin tests
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-TEST-SETUP - Provide testing infrastructure for plugin
- */
-module.exports = {
-  preset: "ts-jest",
-  testEnvironment: "node",
-  testPathIgnorePatterns: ["<rootDir>/lib/"],
-  testMatch: ["<rootDir>/tests/**/*.test.ts"],
-  coveragePathIgnorePatterns: ["<rootDir>/lib/"],
-  coverageThreshold: {
-    global: {
-      branches: 47,
-      functions: 42,
-      lines: 59,
-      statements: 57,
-    },
-  },
-  moduleFileExtensions: ["ts", "js"],
-};

package/scripts/smoke-test.sh

@@ -1,45 +0,0 @@
-#!/bin/bash
-set -e
-
-echo "🧪 Running smoke test for eslint-plugin-traceability"
-echo ""
-
-# Create temporary directory
-workdir=$(mktemp -d)
-echo "📁 Created test directory: $workdir"
-
-# Cleanup on exit
-cleanup() {
-  echo "🧹 Cleaning up test directory"
-  rm -rf "$workdir"
-}
-trap cleanup EXIT
-
-cd "$workdir"
-
-# Initialize npm project
-echo "📦 Initializing npm project..."
-npm init -y > /dev/null
-
-# Install the local package
-echo "📥 Installing eslint-plugin-traceability from local build..."
-npm install "$OLDPWD" > /dev/null
-
-# Create ESLint config (CommonJS format)
-echo "⚙️  Creating ESLint config..."
-cat > eslint.config.js << 'EOF'
-const traceability = require('eslint-plugin-traceability');
-module.exports = [
-  {
-    plugins: { traceability },
-    rules: {}
-  }
-];
-EOF
-
-# Test the plugin loads
-echo "🔍 Testing plugin configuration..."
-npx eslint --print-config eslint.config.js > /dev/null
-
-echo ""
-echo "✅ Smoke test passed! Plugin loads successfully."

package/src/index.ts

@@ -1,56 +0,0 @@
-/**
- * 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

@@ -1,29 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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/report.ts

@@ -1,15 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,28 +0,0 @@
-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

@@ -1,114 +0,0 @@
-/**
- * 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

@@ -1,36 +0,0 @@
-/**
- * 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

@@ -1,52 +0,0 @@
-/**
- * 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;