eslint-plugin-traceability 1.10.1 → 1.11.1

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

@@ -45,6 +45,9 @@ const rule = {
                         uniqueItems: true,
                     },
                     exportPriority: { type: "string", enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES },
+                    annotationTemplate: { type: "string" },
+                    methodAnnotationTemplate: { type: "string" },
+                    autoFix: { type: "boolean" },
                 },
                 additionalProperties: false,
             },
@@ -63,6 +66,15 @@ const rule = {
         const opts = (context.options && context.options[0]) || {};
         const scope = opts.scope || require_story_helpers_1.DEFAULT_SCOPE;
         const exportPriority = opts.exportPriority || "all";
+        const annotationTemplate = typeof opts.annotationTemplate === "string" &&
+            opts.annotationTemplate.trim().length > 0
+            ? opts.annotationTemplate.trim()
+            : undefined;
+        const methodAnnotationTemplate = typeof opts.methodAnnotationTemplate === "string" &&
+            opts.methodAnnotationTemplate.trim().length > 0
+            ? opts.methodAnnotationTemplate.trim()
+            : undefined;
+        const autoFix = typeof opts.autoFix === "boolean" ? opts.autoFix : true;
         /**
          * Optional debug logging for troubleshooting this rule.
          * Developers can temporarily uncomment the block below to log when the rule
@@ -84,6 +96,9 @@ const rule = {
             shouldProcessNode: should,
             scope,
             exportPriority,
+            annotationTemplate,
+            methodAnnotationTemplate,
+            autoFix,
         });
     },
 };

package/lib/src/rules/require-test-traceability.js

@@ -37,12 +37,7 @@ const rule = {
                     testFilePatterns: {
                         type: "array",
                         items: { type: "string" },
-                        default: [
-                            "**/tests/**/*.test.{js,ts}",
-                            "**/tests/**/*.spec.{js,ts}",
-                            "**/__tests__/**/*.{js,ts}",
-                            "**/*.{test,spec}.{js,ts}",
-                        ],
+                        default: ["/tests/", "/test/", "/__tests__", ".test.", ".spec."],
                     },
                     requireDescribeStory: {
                         type: "boolean",

package/lib/src/utils/annotation-checker.js

@@ -76,7 +76,7 @@ function getFixTargetNode(node) {
  * Returned function is a proper named function so no inline arrow is used.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
- * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-AUTOFIX REQ-ANNOTATION-REPORTING
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-AUTOFIX REQ-ANNOTATION-REPORTING
  */
 function createMissingReqFix(node) {
     const target = getFixTargetNode(node);
@@ -90,6 +90,34 @@ function createMissingReqFix(node) {
         return fixer.insertTextBefore(target, "/** @req <REQ-ID> */\n");
     };
 }
+/**
+ * Resolve the display name used when reporting a missing @req annotation.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REPORTING - Use consistent naming when reporting missing @req
+ * @req REQ-ERROR-SPECIFIC - Derive a specific, human-readable name for the node
+ */
+function getReportedName(contextNode, parentNode) {
+    const rawName = (0, require_story_utils_1.getNodeName)(contextNode) ?? (0, require_story_utils_1.getNodeName)(parentNode);
+    return rawName ?? "(anonymous)";
+}
+/**
+ * Determine the AST sub-node that should be used as the location for reporting.
+ * Prefers Identifier nodes (id or key) over the broader function-like node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REPORTING - Report missing @req on the most relevant node
+ * @req REQ-ERROR-SPECIFIC - Target the identifier when available for precise errors
+ */
+function getNameNodeForReqReport(node) {
+    const candidateId = node.id;
+    if (candidateId && candidateId.type === "Identifier") {
+        return candidateId;
+    }
+    const candidateKey = node.key;
+    if (candidateKey && candidateKey.type === "Identifier") {
+        return candidateKey;
+    }
+    return node;
+}
 /**
  * Helper to report a missing @req annotation via the ESLint context API.
  * Uses getNodeName to provide a readable name for the node.
@@ -102,13 +130,9 @@ function createMissingReqFix(node) {
  * @req REQ-ERROR-CONTEXT - Include contextual hints to help understand the error
  */
 function reportMissing(context, node, enableFix = true) {
-    const rawName = (0, require_story_utils_1.getNodeName)(node) ?? (node && (0, require_story_utils_1.getNodeName)(node.parent));
-    const name = rawName ?? "(anonymous)";
-    const nameNode = (node && node.id && node.id.type === "Identifier"
-        ? node.id
-        : node && node.key && node.key.type === "Identifier"
-            ? node.key
-            : node) ?? node;
+    const parentNode = node?.parent;
+    const name = getReportedName(node, parentNode);
+    const nameNode = getNameNodeForReqReport(node);
     const reportOptions = {
         node: nameNode,
         messageId: "missingReq",

package/lib/src/utils/reqAnnotationDetection.js

@@ -138,6 +138,38 @@ function fallbackTextBeforeHasReq(sourceCode, node) {
     }
     return false;
 }
+/**
+ * Helper to combine advanced, location-based heuristics for requirement detection.
+ * Uses preceding lines, parent-chain comments, and fallback text windows to find @req/@supports.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-ANNOTATION-REQ-DETECTION - Use multiple heuristics to detect @req markers around the node
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Use multiple heuristics to detect @supports markers around the node
+ */
+function hasReqInAdvancedHeuristics(sourceCode, node) {
+    if (!sourceCode || !node) {
+        return false;
+    }
+    return (linesBeforeHasReq(sourceCode, node) ||
+        parentChainHasReq(sourceCode, node) ||
+        fallbackTextBeforeHasReq(sourceCode, node));
+}
+/**
+ * Helper to check JSDoc and nearby comments for requirement annotations.
+ * Accepts both @req and @supports markers as evidence of requirement coverage.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation in JSDoc/comments
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @supports as requirement coverage in JSDoc/comments
+ */
+function hasReqInJsdocOrComments(jsdoc, comments) {
+    if (jsdoc &&
+        typeof jsdoc.value === "string" &&
+        (jsdoc.value.includes("@req") || jsdoc.value.includes("@supports"))) {
+        return true;
+    }
+    return comments.some(commentContainsReq);
+}
 /**
  * Helper to determine whether a JSDoc or any nearby comments contain a requirement annotation.
  * Treats both @req and @supports annotations as evidence of requirement coverage.
@@ -151,30 +183,12 @@ function hasReqAnnotation(jsdoc, comments, context, node) {
         const sourceCode = context && typeof context.getSourceCode === "function"
             ? context.getSourceCode()
             : undefined;
-        // Prefer robust, location-based heuristics when sourceCode and node are available.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Use multiple heuristics to detect @req markers around the node
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Use multiple heuristics to detect @supports markers around the node
-        if (sourceCode && node) {
-            if (linesBeforeHasReq(sourceCode, node) ||
-                parentChainHasReq(sourceCode, node) ||
-                fallbackTextBeforeHasReq(sourceCode, node)) {
-                return true;
-            }
+        if (hasReqInAdvancedHeuristics(sourceCode, node)) {
+            return true;
         }
     }
     catch {
-        // Swallow detection errors and fall through to simple checks.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQ-DETECTION - Fail gracefully when advanced detection heuristics throw
+        // swallow and fall through to simple checks
     }
-    // BRANCH requirement detection on JSDoc or comments, accepting both @req and @supports.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
-    // @req REQ-ANNOTATION-REQ-DETECTION
-    // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS
-    return ((jsdoc &&
-        typeof jsdoc.value === "string" &&
-        (jsdoc.value.includes("@req") || jsdoc.value.includes("@supports"))) ||
-        comments.some(commentContainsReq));
+    return hasReqInJsdocOrComments(jsdoc, comments);
 }

package/lib/tests/cli-error-handling.test.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for CLI error handling when plugin loading fails
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-ERROR-HANDLING - Plugin CLI should exit with error on rule load failure
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-ERROR-HANDLING
  */
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));

package/lib/tests/config/eslint-config-validation.test.d.ts

@@ -1 +1,9 @@
+/**
+ * Tests for ESLint config rule schemas.
+ *
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @req REQ-RULE-OPTIONS
+ * @req REQ-CONFIG-VALIDATION
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ */
 export {};

package/lib/tests/config/eslint-config-validation.test.js

@@ -1,4 +1,12 @@
 "use strict";
+/**
+ * Tests for ESLint config rule schemas.
+ *
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @req REQ-RULE-OPTIONS
+ * @req REQ-CONFIG-VALIDATION
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };

package/lib/tests/config/flat-config-presets-integration.test.js

@@ -36,9 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
  * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
- * @req REQ-CONFIG-PRESETS - Validate flat-config presets register traceability plugin and rules
- * @req REQ-FLAT-CONFIG - Ensure presets work with ESLint v9 flat config
- * @req REQ-PROJECT-INTEGRATION - Support seamless integration via documented preset usage
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md REQ-CONFIG-PRESETS REQ-FLAT-CONFIG REQ-PROJECT-INTEGRATION
  */
 const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
 const index_1 = __importStar(require("../../src/index"));

package/lib/tests/config/require-story-annotation-config.test.d.ts

@@ -1 +1,10 @@
+/**
+ * Tests for the require-story-annotation rule schema configuration.
+ *
+ * Verifies that the ESLint rule options for require-story-annotation
+ * define the expected schema properties and constraints.
+ *
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md REQ-RULE-OPTIONS
+ */
 export {};

package/lib/tests/config/require-story-annotation-config.test.js

@@ -1,4 +1,13 @@
 "use strict";
+/**
+ * Tests for the require-story-annotation rule schema configuration.
+ *
+ * Verifies that the ESLint rule options for require-story-annotation
+ * define the expected schema properties and constraints.
+ *
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md REQ-RULE-OPTIONS
+ */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };

package/lib/tests/integration/cli-integration.test.js

@@ -3,6 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for CLI integration of the traceability plugin.
+ * Validates that the plugin registers correctly and enforces
+ * traceability-related rules when invoked via the ESLint CLI.
+ *
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ */
 /**
  * Tests for CLI integration functionality
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
@@ -10,7 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
-describe("[docs/stories/001.0-DEV-PLUGIN-SETUP.story.md] CLI Integration (traceability plugin)", () => {
+describe("CLI Integration (Story 001.0-DEV-PLUGIN-SETUP)", () => {
     const eslintPkgDir = path_1.default.dirname(require.resolve("eslint/package.json"));
     const eslintCliPath = path_1.default.join(eslintPkgDir, "bin", "eslint.js");
     const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");

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

@@ -38,6 +38,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-BATCH - Perform batch updates
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-BATCH REQ-MAINT-VERIFY
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));

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

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-MAINT-REPORT - CLI reporting of stale annotations
  * @req REQ-MAINT-UPDATE - CLI updating of annotation references
  * @req REQ-MAINT-SAFE - Clear exit codes and non-destructive dry-run
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-VERIFY REQ-MAINT-REPORT REQ-MAINT-UPDATE REQ-MAINT-SAFE
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));

package/lib/tests/maintenance/detect-isolated.test.js

@@ -37,6 +37,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
  */
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));

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

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));

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

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-SAFE - Ensure all maintenance tools are exported correctly
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE REQ-MAINT-DETECT REQ-MAINT-UPDATE REQ-MAINT-BATCH REQ-MAINT-VERIFY REQ-MAINT-REPORT
  */
 const maintenance_1 = require("../../src/maintenance");
 describe("Maintenance Tools Index Exports (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {

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

@@ -38,6 +38,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @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
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));

package/lib/tests/maintenance/update-isolated.test.js

@@ -37,6 +37,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - Update annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));

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

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - Update annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
  */
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));

package/lib/tests/perf/maintenance-cli-large-workspace.test.d.ts

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

package/lib/tests/perf/maintenance-cli-large-workspace.test.js

@@ -0,0 +1,130 @@
+"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 });
+/**
+ * CLI-level performance tests for maintenance tools on large workspaces.
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-REPORT REQ-MAINT-SAFE
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const perf_hooks_1 = require("perf_hooks");
+const cli_1 = require("../../src/maintenance/cli");
+function createCliLargeWorkspace() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "traceability-cli-large-"));
+    // Create a modestly sized workspace reusing the same shape as the core perf tests,
+    // but with fewer files to keep end-to-end CLI timing predictable.
+    for (let moduleIndex = 0; moduleIndex < 5; moduleIndex += 1) {
+        const moduleDir = path.join(root, `module-${moduleIndex.toString().padStart(3, "0")}`);
+        fs.mkdirSync(moduleDir);
+        for (let fileIndex = 0; fileIndex < 20; fileIndex += 1) {
+            const filePath = path.join(moduleDir, `file-${fileIndex.toString().padStart(3, "0")}.ts`);
+            const validStory = "cli-valid.story.md";
+            const staleStory = "cli-stale.story.md";
+            const content = `/**
+ * @story ${validStory}
+ * @story ${staleStory}
+ */
+export function cli_example_${moduleIndex}_${fileIndex}() {}
+`;
+            fs.writeFileSync(filePath, content, "utf8");
+        }
+    }
+    // Create the valid story file so that only the stale entries are reported.
+    fs.writeFileSync(path.join(root, "cli-valid.story.md"), "# cli valid", "utf8");
+    return {
+        root,
+        cleanup: () => {
+            fs.rmSync(root, { recursive: true, force: true });
+        },
+    };
+}
+describe("Maintenance CLI on large workspaces (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    let workspace;
+    let originalCwd;
+    beforeAll(() => {
+        originalCwd = process.cwd();
+        workspace = createCliLargeWorkspace();
+        process.chdir(workspace.root);
+    });
+    afterAll(() => {
+        process.chdir(originalCwd);
+        workspace.cleanup();
+    });
+    it("[REQ-MAINT-DETECT] detect --json completes within a generous time budget and returns JSON payload", () => {
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const start = perf_hooks_1.performance.now();
+        const exitCode = (0, cli_1.runMaintenanceCli)([
+            "node",
+            "traceability-maint",
+            "detect",
+            "--root",
+            workspace.root,
+            "--json",
+        ]);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        expect(exitCode === 0 || exitCode === 1).toBe(true);
+        expect(durationMs).toBeLessThan(5000);
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        const payloadRaw = String(logSpy.mock.calls[0][0]);
+        const payload = JSON.parse(payloadRaw);
+        expect(payload.root).toBe(workspace.root);
+        expect(Array.isArray(payload.stale)).toBe(true);
+        expect(payload.stale.length).toBeGreaterThan(0);
+        logSpy.mockRestore();
+    });
+    it("[REQ-MAINT-REPORT] report --format=json completes within a generous time budget", () => {
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const start = perf_hooks_1.performance.now();
+        const exitCode = (0, cli_1.runMaintenanceCli)([
+            "node",
+            "traceability-maint",
+            "report",
+            "--root",
+            workspace.root,
+            "--format",
+            "json",
+        ]);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        expect(exitCode).toBe(0);
+        expect(durationMs).toBeLessThan(5000);
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        const payloadRaw = String(logSpy.mock.calls[0][0]);
+        const payload = JSON.parse(payloadRaw);
+        expect(payload.root).toBe(workspace.root);
+        expect(typeof payload.report).toBe("string");
+        logSpy.mockRestore();
+    });
+});

package/lib/tests/perf/maintenance-large-workspace.test.d.ts

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

package/lib/tests/perf/maintenance-large-workspace.test.js

@@ -0,0 +1,149 @@
+"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 });
+/**
+ * Performance and stress tests for maintenance tools on large workspaces.
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-VERIFY REQ-MAINT-REPORT REQ-MAINT-UPDATE REQ-MAINT-BATCH
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const perf_hooks_1 = require("perf_hooks");
+const detect_1 = require("../../src/maintenance/detect");
+const batch_1 = require("../../src/maintenance/batch");
+const report_1 = require("../../src/maintenance/report");
+const update_1 = require("../../src/maintenance/update");
+/**
+ * Shape of the synthetic large workspace:
+ * - 10 modules (module-000 .. module-009)
+ * - 50 files per module (file-000.ts .. file-049.ts)
+ * - Each file includes a mix of valid and stale @story references.
+ */
+function createLargeWorkspace() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "traceability-large-"));
+    // Create a pool of story files that will be considered "valid".
+    const validStories = [];
+    for (let i = 0; i < 250; i += 1) {
+        const storyName = `valid-story-${i.toString().padStart(4, "0")}.story.md`;
+        const storyPath = path.join(root, storyName);
+        fs.writeFileSync(storyPath, `# ${storyName}`, "utf8");
+        validStories.push(storyName);
+    }
+    let validIndex = 0;
+    let staleIndex = 0;
+    for (let moduleIndex = 0; moduleIndex < 10; moduleIndex += 1) {
+        const moduleDir = path.join(root, `module-${moduleIndex.toString().padStart(3, "0")}`);
+        fs.mkdirSync(moduleDir);
+        for (let fileIndex = 0; fileIndex < 50; fileIndex += 1) {
+            const filePath = path.join(moduleDir, `file-${fileIndex.toString().padStart(3, "0")}.ts`);
+            const validStory = validStories[validIndex % validStories.length] ??
+                "valid-story-0000.story.md";
+            validIndex += 1;
+            const staleStory = `stale-story-${staleIndex
+                .toString()
+                .padStart(4, "0")}.story.md`;
+            staleIndex += 1;
+            const content = `/**
+ * @story ${validStory}
+ * @story ${staleStory}
+ */
+export function example_${moduleIndex}_${fileIndex}() {}
+`;
+            fs.writeFileSync(filePath, content, "utf8");
+        }
+    }
+    return {
+        root,
+        cleanup: () => {
+            fs.rmSync(root, { recursive: true, force: true });
+        },
+    };
+}
+describe("Maintenance tools on large workspaces (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    let workspace;
+    beforeAll(() => {
+        workspace = createLargeWorkspace();
+    });
+    afterAll(() => {
+        workspace.cleanup();
+    });
+    it("[REQ-MAINT-DETECT] detectStaleAnnotations completes within a generous time budget", () => {
+        const start = perf_hooks_1.performance.now();
+        const stale = (0, detect_1.detectStaleAnnotations)(workspace.root);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        // Sanity check: we expect at least some stale entries due to the generated stale-story-* references.
+        expect(stale.length).toBeGreaterThan(0);
+        // Guardrail: this operation should remain comfortably under ~5 seconds on CI hardware.
+        expect(durationMs).toBeLessThan(5000);
+    });
+    it("[REQ-MAINT-VERIFY] verifyAnnotations remains fast on large workspaces", () => {
+        const start = perf_hooks_1.performance.now();
+        const result = (0, batch_1.verifyAnnotations)(workspace.root);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        // With both valid and stale references, verification should report false.
+        expect(result).toBe(false);
+        expect(durationMs).toBeLessThan(5000);
+    });
+    it("[REQ-MAINT-REPORT] generateMaintenanceReport produces output within a generous time budget", () => {
+        const start = perf_hooks_1.performance.now();
+        const report = (0, report_1.generateMaintenanceReport)(workspace.root);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        expect(report).not.toBe("");
+        expect(durationMs).toBeLessThan(5000);
+    });
+    it("[REQ-MAINT-UPDATE] updateAnnotationReferences and batchUpdateAnnotations remain tractable", () => {
+        const exampleOldPath = "stale-story-0000.story.md";
+        const exampleNewPath = "updated-story-0000.story.md";
+        const singleStart = perf_hooks_1.performance.now();
+        const updatedCount = (0, update_1.updateAnnotationReferences)(workspace.root, exampleOldPath, exampleNewPath);
+        const singleDuration = perf_hooks_1.performance.now() - singleStart;
+        expect(updatedCount).toBeGreaterThan(0);
+        expect(singleDuration).toBeLessThan(5000);
+        const batchStart = perf_hooks_1.performance.now();
+        const totalUpdated = (0, batch_1.batchUpdateAnnotations)(workspace.root, [
+            {
+                oldPath: "stale-story-0001.story.md",
+                newPath: "updated-story-0001.story.md",
+            },
+            {
+                oldPath: "stale-story-0002.story.md",
+                newPath: "updated-story-0002.story.md",
+            },
+        ]);
+        const batchDuration = perf_hooks_1.performance.now() - batchStart;
+        expect(totalUpdated).toBeGreaterThanOrEqual(2);
+        expect(batchDuration).toBeLessThan(5000);
+    });
+});

package/lib/tests/plugin-default-export-and-configs.test.js

@@ -35,6 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE REQ-RULE-REGISTRY REQ-CONFIG-SYSTEM
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SEVERITY
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-PLUGIN-STRUCTURE - Validate plugin default export and configs in src/index.ts