eslint-plugin-traceability 1.11.1 → 1.11.3

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

@@ -12,6 +12,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const valid_story_reference_1 = __importDefault(require("../../src/rules/valid-story-reference"));
+const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
+const index_1 = __importDefault(require("../../src/index"));
 /** @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md */
 describe("ESLint Configuration Setup (Story 002.0-DEV-ESLINT-CONFIG)", () => {
     it("[REQ-RULE-OPTIONS] rule meta.schema defines expected properties", () => {
@@ -24,4 +26,75 @@ describe("ESLint Configuration Setup (Story 002.0-DEV-ESLINT-CONFIG)", () => {
         const schema = valid_story_reference_1.default.meta.schema[0];
         expect(schema.additionalProperties).toBe(false);
     });
+    it("[REQ-CONFIG-VALIDATION] ESLint throws on unknown rule option", async () => {
+        const eslint = new use_at_your_own_risk_1.FlatESLint({
+            overrideConfig: [
+                {
+                    plugins: {
+                        traceability: index_1.default,
+                    },
+                    rules: {
+                        "traceability/valid-story-reference": [
+                            "error",
+                            {
+                                storyDirectories: ["stories"],
+                                allowAbsolutePaths: false,
+                                requireStoryExtension: true,
+                                unknownOptionKey: true,
+                            },
+                        ],
+                    },
+                },
+            ],
+            overrideConfigFile: true,
+            ignore: false,
+        });
+        let caughtError;
+        try {
+            await eslint.lintText("const x = 1;");
+        }
+        catch (err) {
+            caughtError = err;
+        }
+        expect(caughtError).toBeInstanceOf(Error);
+        const message = String(caughtError.message || caughtError);
+        expect(message).toContain("traceability/valid-story-reference");
+        expect(message.toLowerCase()).toContain("additional");
+        expect(message.toLowerCase()).toContain("unexpected property");
+        expect(message).toContain("unknownOptionKey");
+    });
+    it("[REQ-CONFIG-VALIDATION] ESLint throws on invalid option type", async () => {
+        const eslint = new use_at_your_own_risk_1.FlatESLint({
+            overrideConfig: [
+                {
+                    plugins: {
+                        traceability: index_1.default,
+                    },
+                    rules: {
+                        "traceability/valid-story-reference": [
+                            "error",
+                            {
+                                // storyDirectories must be an array, not a string
+                                storyDirectories: "not-an-array",
+                            },
+                        ],
+                    },
+                },
+            ],
+            overrideConfigFile: true,
+            ignore: false,
+        });
+        let caughtError;
+        try {
+            await eslint.lintText("const y = 2;");
+        }
+        catch (err) {
+            caughtError = err;
+        }
+        expect(caughtError).toBeInstanceOf(Error);
+        const message = String(caughtError.message || caughtError);
+        expect(message).toContain("traceability/valid-story-reference");
+        expect(message).toContain("not-an-array");
+        expect(message.toLowerCase()).toContain("array");
+    });
 });

package/lib/tests/fixtures/stale/example.js

@@ -1,3 +1,3 @@
 "use strict";
 // Sample code with stale annotation
-// @story non-existent.md
+// @story docs/stories/non-existent.story.md

package/lib/tests/fixtures/update/example.js

@@ -1,3 +1,3 @@
 "use strict";
 // Sample code with annotation to update
-// @story old.md
+// @story docs/stories/old.story.md

package/lib/tests/integration/catch-annotation-prettier.integration.test.d.ts

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

package/lib/tests/integration/catch-annotation-prettier.integration.test.js

@@ -0,0 +1,131 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Prettier integration tests for CatchClause annotation positions.
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-PRETTIER-COMPATIBILITY
+ */
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+describe("CatchClause annotations with Prettier (Story 025.0-DEV-CATCH-ANNOTATION-POSITION)", () => {
+    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");
+    const prettierPackageJson = require.resolve("prettier/package.json");
+    const prettierCliPath = path_1.default.join(path_1.default.dirname(prettierPackageJson), "bin", "prettier.cjs");
+    function runEslintWithRequireBranchAnnotation(code) {
+        const args = [
+            "--no-config-lookup",
+            "--config",
+            configPath,
+            "--stdin",
+            "--stdin-filename",
+            "catch.js",
+            "--rule",
+            "no-unused-vars:off",
+            "--rule",
+            "no-magic-numbers:off",
+            "--rule",
+            "no-undef:off",
+            "--rule",
+            "no-console:off",
+            "--rule",
+            "traceability/require-branch-annotation:error",
+        ];
+        return (0, child_process_1.spawnSync)(process.execPath, [eslintCliPath, ...args], {
+            encoding: "utf-8",
+            input: code,
+        });
+    }
+    function formatWithPrettier(source) {
+        const result = (0, child_process_1.spawnSync)(process.execPath, [prettierCliPath, "--parser", "typescript"], {
+            encoding: "utf-8",
+            input: source,
+        });
+        if (result.status !== 0) {
+            throw new Error(`Prettier formatting failed: ${result.stderr || result.stdout}`);
+        }
+        return result.stdout;
+    }
+    it("[REQ-PRETTIER-COMPATIBILITY-BEFORE] accepts code where annotations start before catch but are moved inside by Prettier", () => {
+        const original = `
+function doSomething() {
+  return 42;
+}
+
+function handleError(error) {
+  console.error(error);
+}
+
+// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+}
+// @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+// @req REQ-CATCH-PATH
+catch (error) {
+  handleError(error);
+}
+`;
+        const formatted = formatWithPrettier(original);
+        // Sanity check: Prettier should move the branch annotations inside the catch body.
+        expect(formatted).toContain("catch (error) {");
+        const catchIndex = formatted.indexOf("catch (error) {");
+        const storyIndex = formatted.indexOf("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(storyIndex).toBeGreaterThan(catchIndex);
+        const result = runEslintWithRequireBranchAnnotation(formatted);
+        expect(result.status).toBe(0);
+    });
+    it("[REQ-PRETTIER-COMPATIBILITY-INSIDE] accepts code where annotations start inside the catch body and are preserved by Prettier", () => {
+        const original = `
+function doSomething() {
+  return 42;
+}
+
+function handleError(error) {
+  console.error(error);
+}
+
+// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+} catch (error) {
+  // @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+  // @req REQ-CATCH-INSIDE
+  handleError(error);
+}
+`;
+        const formatted = formatWithPrettier(original);
+        // Sanity: annotations should still be associated with the catch body after formatting.
+        expect(formatted).toContain("catch (error) {");
+        const catchIndex = formatted.indexOf("catch (error) {");
+        const storyIndex = formatted.indexOf("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(storyIndex).toBeGreaterThan(catchIndex);
+        const result = runEslintWithRequireBranchAnnotation(formatted);
+        expect(result.status).toBe(0);
+    });
+    it("[REQ-PRETTIER-COMPATIBILITY-EMPTY] accepts empty catch blocks with inside-catch annotations after Prettier formatting", () => {
+        const original = `
+function doSomething() {
+  return 42;
+}
+
+// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+} catch (error) {
+  // @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+  // @req REQ-CATCH-EMPTY
+}
+`;
+        const formatted = formatWithPrettier(original);
+        const result = runEslintWithRequireBranchAnnotation(formatted);
+        expect(result.status).toBe(0);
+    });
+});

package/lib/tests/integration/dogfooding-validation.test.d.ts

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

package/lib/tests/integration/dogfooding-validation.test.js

@@ -0,0 +1,94 @@
+"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 });
+/**
+ * Dogfooding validation integration tests
+ * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-TEST REQ-DOGFOODING-CI
+ */
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+/**
+ * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-TEST
+ */
+function getTsConfigFromEslintConfig(eslintConfig) {
+    const configs = Array.isArray(eslintConfig) ? eslintConfig : [eslintConfig];
+    return configs.find((config) => {
+        if (!config || !config.files)
+            return false;
+        const files = config.files;
+        return files.includes("**/*.ts") && files.includes("**/*.tsx");
+    });
+}
+describe("Dogfooding Validation (Story 023.0-MAINT-DOGFOODING-VALIDATION)", () => {
+    it("[REQ-DOGFOODING-TEST] should have traceability/require-story-annotation enabled for TS sources", () => {
+        /**
+         * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-TEST
+         */
+        // Require the project's eslint.config.js and find the TS-specific config
+        // that applies to *.ts and *.tsx files.
+        const eslintConfig = require("../../eslint.config.js");
+        const tsConfig = getTsConfigFromEslintConfig(eslintConfig);
+        expect(tsConfig).toBeDefined();
+        const rules = tsConfig.rules || {};
+        const ruleEntry = rules["traceability/require-story-annotation"];
+        expect(ruleEntry).toBeDefined();
+        const severity = Array.isArray(ruleEntry) && ruleEntry.length > 0
+            ? ruleEntry[0]
+            : ruleEntry;
+        expect(severity).toBe("error");
+    });
+    it("[REQ-DOGFOODING-CI] should run traceability/require-story-annotation via ESLint CLI on TS sources", () => {
+        /**
+         * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-CI
+         */
+        const eslintBin = path.resolve(__dirname, "../../node_modules/.bin/eslint");
+        const configPath = path.resolve(__dirname, "../../eslint.config.js");
+        const tsSnippet = `
+      const x: number = 42;
+      export function foo() {
+        return x;
+      }
+    `;
+        const result = (0, child_process_1.spawnSync)(process.platform === "win32" ? `${eslintBin}.cmd` : eslintBin, ["--config", configPath, "--stdin", "--stdin-filename", "src/dogfood.ts"], {
+            encoding: "utf8",
+            input: tsSnippet,
+        });
+        // The snippet intentionally lacks @story annotations, so the rule should
+        // report an error for the generated `src/dogfood.ts` virtual file.
+        expect(result.status).not.toBe(0);
+        expect(result.stdout).toContain("error");
+        expect(result.stdout).toContain("src/dogfood.ts");
+    });
+});

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

@@ -58,6 +58,26 @@ describe("Maintenance CLI (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
             temp.cleanup();
         }
     });
+    it("[REQ-MAINT-VERIFY] verify exits with code 1 and prints guidance when annotations are stale or invalid", () => {
+        const temp = (0, temp_dir_helpers_1.createTempDir)("maint-cli-");
+        const dir = temp.dir;
+        process.chdir(dir);
+        const tsContent = `/**\n * @story missing.story.md\n */`;
+        fs_1.default.writeFileSync(path_1.default.join(dir, "file.ts"), tsContent, "utf8");
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const code = (0, cli_1.runMaintenanceCli)(["node", "traceability-maint", "verify"]);
+        try {
+            expect(code).toBe(1);
+            expect(logSpy).toHaveBeenCalledTimes(1);
+            const message = String(logSpy.mock.calls[0][0]);
+            expect(message).toContain("Stale or invalid traceability annotations detected under");
+            expect(message).toContain("Run 'traceability-maint detect' or 'traceability-maint report' for details.");
+        }
+        finally {
+            logSpy.mockRestore();
+            temp.cleanup();
+        }
+    });
     it("[REQ-MAINT-REPORT] report prints human-readable summary and exits 0", () => {
         const temp = (0, temp_dir_helpers_1.createTempDir)("maint-cli-");
         const dir = temp.dir;
@@ -77,6 +97,23 @@ describe("Maintenance CLI (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
             temp.cleanup();
         }
     });
+    it("[REQ-MAINT-REPORT] report prints 'nothing to report' when no stale annotations exist", () => {
+        const temp = (0, temp_dir_helpers_1.createTempDir)("maint-cli-");
+        const dir = temp.dir;
+        process.chdir(dir);
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const code = (0, cli_1.runMaintenanceCli)(["node", "traceability-maint", "report"]);
+        try {
+            expect(code).toBe(0);
+            expect(logSpy).toHaveBeenCalled();
+            const allMessages = logSpy.mock.calls.flat().join("\n");
+            expect(allMessages).toContain("No stale @story annotations found. Nothing to report.");
+        }
+        finally {
+            logSpy.mockRestore();
+            temp.cleanup();
+        }
+    });
     it("[REQ-MAINT-UPDATE] update performs replacements and exits 0", () => {
         const temp = (0, temp_dir_helpers_1.createTempDir)("maint-cli-");
         const dir = temp.dir;

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

@@ -57,26 +57,26 @@ describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)",
             const filePath2 = path.join(nestedDir, "file2.ts");
             const content1 = `
 /**
- * @story stale1.story.md
+ * @story docs/stories/non-existent-story.story.md
  */
 `;
             fs.writeFileSync(filePath1, content1, "utf8");
             const content2 = `
 /**
- * @story stale2.story.md
+ * @story docs/stories/another-non-existent.story.md
  */
 `;
             fs.writeFileSync(filePath2, content2, "utf8");
             const result = (0, detect_1.detectStaleAnnotations)(tmpDir);
             expect(result).toHaveLength(2);
-            expect(result).toContain("stale1.story.md");
-            expect(result).toContain("stale2.story.md");
+            expect(result).toContain("docs/stories/non-existent-story.story.md");
+            expect(result).toContain("docs/stories/another-non-existent.story.md");
         }
         finally {
             fs.rmSync(tmpDir, { recursive: true, force: true });
         }
     });
-    it("[REQ-MAINT-DETECT] throws error on permission denied", () => {
+    it("[REQ-MAINT-DETECT] handles permission denied errors by returning an empty result", () => {
         const tmpDir2 = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-perm-"));
         const dir = path.join(tmpDir2, "subdir");
         fs.mkdirSync(dir);

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

@@ -127,4 +127,22 @@ describe("Maintenance CLI on large workspaces (Story 009.0-DEV-MAINTENANCE-TOOLS
         expect(typeof payload.report).toBe("string");
         logSpy.mockRestore();
     });
+    it("[REQ-MAINT-VERIFY] verify completes within a generous time budget and reports stale annotations", () => {
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const start = perf_hooks_1.performance.now();
+        const exitCode = (0, cli_1.runMaintenanceCli)([
+            "node",
+            "traceability-maint",
+            "verify",
+            "--root",
+            workspace.root,
+        ]);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        expect(exitCode).toBe(1);
+        expect(durationMs).toBeLessThan(5000);
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        const message = String(logSpy.mock.calls[0][0]);
+        expect(message).toContain("Stale or invalid traceability annotations detected under");
+        logSpy.mockRestore();
+    });
 });

package/lib/tests/perf/require-branch-annotation-large-file.test.d.ts

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

package/lib/tests/perf/require-branch-annotation-large-file.test.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Performance tests for require-branch-annotation on large nested-branch files.
+ *
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-PERFORMANCE-OPTIMIZATION REQ-NESTED-HANDLING
+ */
+const eslint_1 = require("eslint");
+const perf_hooks_1 = require("perf_hooks");
+const require_branch_annotation_1 = __importDefault(require("../../src/rules/require-branch-annotation"));
+/**
+ * Build a large source file containing many nested branch structures
+ * (if-statements within if-statements) to exercise the rule at scale.
+ *
+ * The generated code intentionally omits annotations so that the rule
+ * produces diagnostics for both outer and inner branches.
+ */
+function buildLargeNestedBranchSource(functionCount, nestingDepth) {
+    const lines = [];
+    for (let i = 0; i < functionCount; i += 1) {
+        lines.push(`function fn_${i}() {`);
+        lines.push("  let x = 0;");
+        // Create a staircase of nested if-statements.
+        for (let depth = 0; depth < nestingDepth; depth += 1) {
+            const indent = "  ".repeat(depth + 1);
+            lines.push(`${indent}if (x > ${depth}) {`);
+        }
+        const innerIndent = "  ".repeat(nestingDepth + 1);
+        lines.push(`${innerIndent}if (x % 2 === 0) {`);
+        lines.push(`${innerIndent}  x++;`);
+        lines.push(`${innerIndent}} else {`);
+        lines.push(`${innerIndent}  x--;`);
+        lines.push(`${innerIndent}}`);
+        // Close all nested if blocks.
+        for (let depth = nestingDepth - 1; depth >= 0; depth -= 1) {
+            const indent = "  ".repeat(depth + 1);
+            lines.push(`${indent}}`);
+        }
+        lines.push("}");
+    }
+    return lines.join("\n");
+}
+describe("require-branch-annotation performance on large nested-branch files (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
+    const ruleName = "traceability/require-branch-annotation";
+    it("[REQ-PERFORMANCE-OPTIMIZATION] analyzes a large nested-branch file within a generous time budget", () => {
+        const linter = new eslint_1.Linter({ configType: "eslintrc" });
+        linter.defineRule(ruleName, require_branch_annotation_1.default);
+        // 200 functions each with several nested branches gives us
+        // a substantial number of branch nodes without being extreme.
+        const source = buildLargeNestedBranchSource(200, 3);
+        const start = perf_hooks_1.performance.now();
+        const messages = linter.verify(source, {
+            parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+            rules: {
+                [ruleName]: "error",
+            },
+        });
+        const durationMs = perf_hooks_1.performance.now() - start;
+        // Sanity check: we expect diagnostics for many branches.
+        expect(messages.length).toBeGreaterThan(0);
+        // Guardrail: keep analysis comfortably under ~5 seconds on CI hardware.
+        expect(durationMs).toBeLessThan(5000);
+    });
+});

package/lib/tests/perf/valid-annotation-format-large-file.test.d.ts

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

package/lib/tests/perf/valid-annotation-format-large-file.test.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Performance tests for valid-annotation-format on large annotated files.
+ *
+ * @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-MULTILINE-SUPPORT REQ-FLEXIBLE-PARSING REQ-SYNTAX-VALIDATION
+ */
+const eslint_1 = require("eslint");
+const perf_hooks_1 = require("perf_hooks");
+const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));
+/**
+ * Build a large source file containing many functions with traceability
+ * annotations in both line and block comments.
+ *
+ * The generated code mixes valid and invalid annotation formats to exercise
+ * parsing, multi-line handling, and error-reporting paths at scale without
+ * relying on auto-fix.
+ */
+function buildLargeAnnotatedSource(functionCount, annotationsPerFunction) {
+    const lines = [];
+    for (let i = 0; i < functionCount; i += 1) {
+        // JSDoc-style block comment with multi-line @story/@req values.
+        lines.push("/**");
+        lines.push(" * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md");
+        lines.push(" * @req REQ-FORMAT-SPECIFICATION");
+        lines.push(" */");
+        // Additional line comments with a mix of valid and intentionally
+        // invalid formats (missing extensions, traversal, malformed IDs).
+        for (let j = 0; j < annotationsPerFunction; j += 1) {
+            const selector = (i + j) % 4;
+            if (selector === 0) {
+                lines.push("// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story");
+            }
+            else if (selector === 1) {
+                lines.push("// @req REQ-EXAMPLE-" + i.toString(10));
+            }
+            else if (selector === 2) {
+                lines.push("// @story ../outside-project.story.md");
+            }
+            else {
+                lines.push("// @req invalid-format-id");
+            }
+        }
+        lines.push(`function annotated_fn_${i}() {`);
+        lines.push('  return "ok";\n}');
+    }
+    return lines.join("\n");
+}
+describe("valid-annotation-format performance on large annotated files (Story 005.0-DEV-ANNOTATION-VALIDATION)", () => {
+    const ruleName = "traceability/valid-annotation-format";
+    it("[REQ-MULTILINE-SUPPORT][REQ-FLEXIBLE-PARSING] analyzes a large annotated file within a generous time budget", () => {
+        const linter = new eslint_1.Linter({ configType: "eslintrc" });
+        linter.defineRule(ruleName, valid_annotation_format_1.default);
+        // 150 functions each with several annotations provides a substantial
+        // volume of comments and annotation patterns without being extreme.
+        const source = buildLargeAnnotatedSource(150, 3);
+        const start = perf_hooks_1.performance.now();
+        const messages = linter.verify(source, {
+            parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+            rules: {
+                [ruleName]: "error",
+            },
+        });
+        const durationMs = perf_hooks_1.performance.now() - start;
+        // Sanity check: we expect diagnostics for some invalid annotations so the
+        // rule is definitely executing its validation logic.
+        expect(messages.length).toBeGreaterThan(0);
+        // Guardrail: keep analysis comfortably under ~5 seconds on CI hardware.
+        expect(durationMs).toBeLessThan(5000);
+    });
+});

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

@@ -59,6 +59,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
             "valid-req-reference",
             "prefer-implements-annotation",
             "require-test-traceability",
+            "prefer-supports-annotation",
         ];
         // Act: get actual rule names from plugin
         const actual = Object.keys(index_1.rules);

package/lib/tests/plugin-setup.test.js

@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE REQ-NPM-PACKAGE
  */
 const index_1 = __importStar(require("../src/index"));
 describe("Traceability ESLint Plugin (Story 001.0-DEV-PLUGIN-SETUP)", () => {
@@ -48,4 +48,15 @@ describe("Traceability ESLint Plugin (Story 001.0-DEV-PLUGIN-SETUP)", () => {
         expect(index_1.default.rules).toBe(index_1.rules);
         expect(index_1.default.configs).toBe(index_1.configs);
     });
+    it("[REQ-PLUGIN-STRUCTURE][REQ-NPM-PACKAGE] plugin exposes meta with name, namespace, and version", () => {
+        // Arrange
+        const pkg = require("../package.json");
+        // Act
+        const meta = index_1.default.meta;
+        // Assert
+        expect(meta).toBeDefined();
+        expect(meta.name).toBe(pkg.name);
+        expect(meta.version).toBe(pkg.version);
+        expect(meta.namespace).toBe("traceability");
+    });
 });