eslint-plugin-traceability 1.0.0

package/eslint.config.js

@@ -0,0 +1,146 @@
+/**
+ * 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: 90, skipBlankLines: true, skipComments: true }],
+      // Enforce maximum lines per file for maintainability
+      "max-lines": ["error", { max: 400, 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: 90, skipBlankLines: true, skipComments: true }],
+      // Enforce maximum lines per file for maintainability
+      "max-lines": ["error", { max: 400, 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

@@ -0,0 +1,21 @@
+/****
+ * 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/lib/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ESLint Traceability Plugin
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
+ */
+export declare const rules: Record<string, unknown>;
+export declare const configs: {
+  recommended: {
+    rules: {};
+  }[];
+  strict: {
+    rules: {};
+  }[];
+};
+declare const _default: {
+  rules: Record<string, unknown>;
+  configs: {
+    recommended: {
+      rules: {};
+    }[];
+    strict: {
+      rules: {};
+    }[];
+  };
+};
+export default _default;

package/lib/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * ESLint Traceability Plugin
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
+ */
+const plugin = require("./src/index.js");
+
+module.exports = plugin;
+module.exports.rules = plugin.rules;
+module.exports.configs = plugin.configs;

package/lib/src/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ESLint Traceability Plugin
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
+ */
+export declare const rules: {
+    "require-story-annotation": any;
+    "require-req-annotation": any;
+    "require-branch-annotation": any;
+    "valid-annotation-format": any;
+    "valid-story-reference": import("eslint").Rule.RuleModule;
+    "valid-req-reference": import("eslint").Rule.RuleModule;
+};
+export declare const configs: {
+    recommended: {
+        plugins: {
+            traceability: {};
+        };
+        rules: {
+            "traceability/require-story-annotation": string;
+            "traceability/require-req-annotation": string;
+            "traceability/require-branch-annotation": string;
+            "traceability/valid-annotation-format": string;
+            "traceability/valid-story-reference": string;
+            "traceability/valid-req-reference": string;
+        };
+    }[];
+    strict: {
+        plugins: {
+            traceability: {};
+        };
+        rules: {
+            "traceability/require-story-annotation": string;
+            "traceability/require-req-annotation": string;
+            "traceability/require-branch-annotation": string;
+            "traceability/valid-annotation-format": string;
+            "traceability/valid-story-reference": string;
+            "traceability/valid-req-reference": string;
+        };
+    }[];
+};
+declare const _default: {
+    rules: {
+        "require-story-annotation": any;
+        "require-req-annotation": any;
+        "require-branch-annotation": any;
+        "valid-annotation-format": any;
+        "valid-story-reference": import("eslint").Rule.RuleModule;
+        "valid-req-reference": import("eslint").Rule.RuleModule;
+    };
+    configs: {
+        recommended: {
+            plugins: {
+                traceability: {};
+            };
+            rules: {
+                "traceability/require-story-annotation": string;
+                "traceability/require-req-annotation": string;
+                "traceability/require-branch-annotation": string;
+                "traceability/valid-annotation-format": string;
+                "traceability/valid-story-reference": string;
+                "traceability/valid-req-reference": string;
+            };
+        }[];
+        strict: {
+            plugins: {
+                traceability: {};
+            };
+            rules: {
+                "traceability/require-story-annotation": string;
+                "traceability/require-req-annotation": string;
+                "traceability/require-branch-annotation": string;
+                "traceability/valid-annotation-format": string;
+                "traceability/valid-story-reference": string;
+                "traceability/valid-req-reference": string;
+            };
+        }[];
+    };
+};
+export default _default;

package/lib/src/index.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * ESLint Traceability Plugin
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configs = exports.rules = void 0;
+const require_story_annotation_1 = __importDefault(require("./rules/require-story-annotation"));
+const require_req_annotation_1 = __importDefault(require("./rules/require-req-annotation"));
+const require_branch_annotation_1 = __importDefault(require("./rules/require-branch-annotation"));
+const valid_annotation_format_1 = __importDefault(require("./rules/valid-annotation-format"));
+const valid_story_reference_1 = __importDefault(require("./rules/valid-story-reference"));
+const valid_req_reference_1 = __importDefault(require("./rules/valid-req-reference"));
+exports.rules = {
+    "require-story-annotation": require_story_annotation_1.default,
+    "require-req-annotation": require_req_annotation_1.default,
+    "require-branch-annotation": require_branch_annotation_1.default,
+    "valid-annotation-format": valid_annotation_format_1.default,
+    "valid-story-reference": valid_story_reference_1.default,
+    "valid-req-reference": valid_req_reference_1.default,
+};
+exports.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",
+            },
+        },
+    ],
+};
+exports.default = { rules: exports.rules, configs: exports.configs };

package/lib/src/maintenance/batch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function batchUpdateAnnotations(codebasePath: string, mappings: {
+    oldPath: string;
+    newPath: string;
+}[]): number;
+/**
+ * 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 declare function verifyAnnotations(codebasePath: string): boolean;

package/lib/src/maintenance/batch.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.batchUpdateAnnotations = batchUpdateAnnotations;
+exports.verifyAnnotations = verifyAnnotations;
+const update_1 = require("./update");
+const detect_1 = require("./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
+ */
+function batchUpdateAnnotations(codebasePath, mappings) {
+    let totalUpdated = 0;
+    for (const { oldPath, newPath } of mappings) {
+        totalUpdated += (0, update_1.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
+ */
+function verifyAnnotations(codebasePath) {
+    const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);
+    return staleAnnotations.length === 0;
+}

package/lib/src/maintenance/detect.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function detectStaleAnnotations(codebasePath: string): string[];

package/lib/src/maintenance/detect.js

@@ -0,0 +1,69 @@
+"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.detectStaleAnnotations = detectStaleAnnotations;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const utils_1 = require("./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
+ */
+function detectStaleAnnotations(codebasePath) {
+    if (!fs.existsSync(codebasePath) ||
+        !fs.statSync(codebasePath).isDirectory()) {
+        return [];
+    }
+    const cwd = process.cwd();
+    const baseDir = path.resolve(cwd, codebasePath);
+    const stale = new Set();
+    const files = (0, utils_1.getAllFiles)(codebasePath);
+    for (const file of files) {
+        const content = fs.readFileSync(file, "utf8");
+        const regex = /@story\s+([^\s]+)/g;
+        let match;
+        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/lib/src/maintenance/index.d.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/lib/src/maintenance/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMaintenanceReport = exports.verifyAnnotations = exports.batchUpdateAnnotations = exports.updateAnnotationReferences = exports.detectStaleAnnotations = void 0;
+/**
+ * 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
+ */
+var detect_1 = require("./detect");
+Object.defineProperty(exports, "detectStaleAnnotations", { enumerable: true, get: function () { return detect_1.detectStaleAnnotations; } });
+var update_1 = require("./update");
+Object.defineProperty(exports, "updateAnnotationReferences", { enumerable: true, get: function () { return update_1.updateAnnotationReferences; } });
+var batch_1 = require("./batch");
+Object.defineProperty(exports, "batchUpdateAnnotations", { enumerable: true, get: function () { return batch_1.batchUpdateAnnotations; } });
+Object.defineProperty(exports, "verifyAnnotations", { enumerable: true, get: function () { return batch_1.verifyAnnotations; } });
+var report_1 = require("./report");
+Object.defineProperty(exports, "generateMaintenanceReport", { enumerable: true, get: function () { return report_1.generateMaintenanceReport; } });

package/lib/src/maintenance/report.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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 declare function generateMaintenanceReport(codebasePath: string): string;

package/lib/src/maintenance/report.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMaintenanceReport = generateMaintenanceReport;
+const detect_1 = require("./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
+ */
+function generateMaintenanceReport(codebasePath) {
+    const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);
+    if (staleAnnotations.length === 0) {
+        return "";
+    }
+    return staleAnnotations.join("\n");
+}

package/lib/src/maintenance/update.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function updateAnnotationReferences(codebasePath: string, oldPath: string, newPath: string): number;

package/lib/src/maintenance/update.js

@@ -0,0 +1,67 @@
+"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.updateAnnotationReferences = updateAnnotationReferences;
+const fs = __importStar(require("fs"));
+const utils_1 = require("./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
+ */
+function updateAnnotationReferences(codebasePath, oldPath, newPath) {
+    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 = (0, utils_1.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/lib/src/maintenance/utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function getAllFiles(dir: string): string[];