npm - eslint-plugin-traceability - Versions diffs - 1.11.2 → 1.11.4 - Mend

eslint-plugin-traceability 1.11.2 → 1.11.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

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

@@ -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 CHANGED Viewed

@@ -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/rules/prefer-implements-annotation.test.js CHANGED Viewed

@@ -18,80 +18,87 @@ const ruleTester = new eslint_1.RuleTester({
         parserOptions: { ecmaVersion: 2020, sourceType: "module" },
     },
 });
-describe("prefer-implements-annotation rule (Story 010.3-DEV-MIGRATE-TO-SUPPORTS)", () => {
-    ruleTester.run("prefer-implements-annotation", prefer_implements_annotation_1.default, {
-        valid: [
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @story is ignored",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction onlyStory() {}`,
-            },
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @req is ignored",
-                code: `/**\n * @req REQ-ONLY\n */\nfunction onlyReq() {}`,
-            },
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @supports only is ignored",
-                code: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction alreadyImplements() {}`,
-            },
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @story and @supports but no @req is ignored",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction storyAndSupportsNoReq() {}`,
-            },
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @req and @supports but no @story is ignored",
-                code: `/**\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction reqAndSupportsNoStory() {}`,
-            },
-        ],
-        invalid: [
-            {
-                name: "[REQ-OPTIONAL-WARNING] single-story @story + @req block triggers preferImplements message",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
-                output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-MULTI-STORY-DETECT] mixed @story/@req and @supports triggers cannotAutoFix",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction mixed() {}`,
-                errors: [
-                    {
-                        messageId: "cannotAutoFix",
-                        data: {
-                            reason: "comment mixes @story/@req with existing @supports annotations",
-                        },
+describe("prefer-supports-annotation / prefer-implements-annotation aliasing (Story 010.3-DEV-MIGRATE-TO-SUPPORTS)", () => {
+    const valid = [
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @story is ignored",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction onlyStory() {}`,
+        },
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @req is ignored",
+            code: `/**\n * @req REQ-ONLY\n */\nfunction onlyReq() {}`,
+        },
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @supports only is ignored",
+            code: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction alreadyImplements() {}`,
+        },
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @story and @supports but no @req is ignored",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction storyAndSupportsNoReq() {}`,
+        },
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @req and @supports but no @story is ignored",
+            code: `/**\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction reqAndSupportsNoStory() {}`,
+        },
+    ];
+    const invalid = [
+        {
+            name: "[REQ-OPTIONAL-WARNING] single-story @story + @req block triggers preferImplements message",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+            output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-MULTI-STORY-DETECT] mixed @story/@req and @supports triggers cannotAutoFix",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction mixed() {}`,
+            errors: [
+                {
+                    messageId: "cannotAutoFix",
+                    data: {
+                        reason: "comment mixes @story/@req with existing @supports annotations",
                     },
-                ],
-            },
-            {
-                name: "[REQ-MULTI-STORY-DETECT] multiple @story paths in same block trigger multiStoryDetected",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n * @req REQ-BRANCH-DETECTION\n */\nfunction multiStory() {}`,
-                errors: [{ messageId: "multiStoryDetected" }],
-            },
-            {
-                name: "[REQ-AUTO-FIX] single @story + single @req auto-fixes to single @supports line",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
-                output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-SINGLE-STORY-FIX] single @story with multiple @req lines auto-fixes to single @supports line containing all REQ IDs",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ONE\n * @req REQ-TWO\n * @req REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
-                output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ONE REQ-TWO REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-AUTO-FIX] complex @req content (extra description) does not auto-fix but still warns",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED must handle extra description\n */\nfunction complexReqNoAutoFix() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-AUTO-FIX] complex @story content (extra description) does not auto-fix but still warns",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md additional descriptive text\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction complexStoryNoAutoFix() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-        ],
+                },
+            ],
+        },
+        {
+            name: "[REQ-MULTI-STORY-DETECT] multiple @story paths in same block trigger multiStoryDetected",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n * @req REQ-BRANCH-DETECTION\n */\nfunction multiStory() {}`,
+            errors: [{ messageId: "multiStoryDetected" }],
+        },
+        {
+            name: "[REQ-AUTO-FIX] single @story + single @req auto-fixes to single @supports line",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+            output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-SINGLE-STORY-FIX] single @story with multiple @req lines auto-fixes to single @supports line containing all REQ IDs",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ONE\n * @req REQ-TWO\n * @req REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+            output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ONE REQ-TWO REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-AUTO-FIX] complex @req content (extra description) does not auto-fix but still warns",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED must handle extra description\n */\nfunction complexReqNoAutoFix() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-AUTO-FIX] complex @story content (extra description) does not auto-fix but still warns",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md additional descriptive text\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction complexStoryNoAutoFix() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+    ];
+    ruleTester.run("prefer-implements-annotation", prefer_implements_annotation_1.default, {
+        valid,
+        invalid,
+    });
+    ruleTester.run("prefer-supports-annotation", prefer_implements_annotation_1.default, {
+        valid,
+        invalid,
     });
 });
 describe("prefer-implements-annotation configuration severity (REQ-CONFIG-SEVERITY)", () => {
+    // Story 010.3 / REQ-RULE-NAME: verify aliasing semantics for new primary rule name and deprecated alias
     test("rule is disabled by default in recommended and strict presets (not present in preset rule maps)", () => {
         const recommended = src_1.configs.recommended;
         expect(Array.isArray(recommended)).toBe(true);
@@ -99,27 +106,34 @@ describe("prefer-implements-annotation configuration severity (REQ-CONFIG-SEVERI
         expect(firstConfig).toBeDefined();
         const rules = firstConfig.rules || {};
         expect(rules["traceability/prefer-implements-annotation"]).toBeUndefined();
+        expect(rules["traceability/prefer-supports-annotation"]).toBeUndefined();
         const strict = src_1.configs.strict;
         expect(Array.isArray(strict)).toBe(true);
         const strictFirstConfig = strict[0];
         expect(strictFirstConfig).toBeDefined();
         const strictRules = strictFirstConfig.rules || {};
         expect(strictRules["traceability/prefer-implements-annotation"]).toBeUndefined();
+        expect(strictRules["traceability/prefer-supports-annotation"]).toBeUndefined();
     });
     test("rule can be configured with severity 'warn' or 'error' in flat config", () => {
+        // Story 010.3 / REQ-RULE-NAME: both primary and alias rule keys must be accepted in flat config
         const flatWarnConfig = {
             files: ["**/*.ts"],
             rules: {
                 "traceability/prefer-implements-annotation": "warn",
+                "traceability/prefer-supports-annotation": "warn",
             },
         };
         expect(flatWarnConfig.rules["traceability/prefer-implements-annotation"]).toBe("warn");
+        expect(flatWarnConfig.rules["traceability/prefer-supports-annotation"]).toBe("warn");
         const flatErrorConfig = {
             files: ["**/*.ts"],
             rules: {
                 "traceability/prefer-implements-annotation": "error",
+                "traceability/prefer-supports-annotation": "error",
             },
         };
         expect(flatErrorConfig.rules["traceability/prefer-implements-annotation"]).toBe("error");
+        expect(flatErrorConfig.rules["traceability/prefer-supports-annotation"]).toBe("error");
     });
 });

package/lib/tests/rules/require-branch-annotation.test.js CHANGED Viewed

@@ -4,9 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md, docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md, docs/stories/007.0-DEV-ERROR-REPORTING.story.md, docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @req REQ-BRANCH-DETECTION - Verify require-branch-annotation rule enforces branch annotations
  * @req REQ-ERROR-SPECIFIC - Branch-level missing-annotation error messages are specific and informative
  * @req REQ-ERROR-CONSISTENCY - Branch-level missing-annotation error messages follow shared conventions
@@ -14,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-NESTED-HANDLING - Nested branch annotations are correctly enforced without duplicative reporting
  * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION REQ-NESTED-HANDLING
  * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-CONSISTENCY REQ-ERROR-SUGGESTION
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF REQ-POSITION-PRIORITY-ELSE-IF REQ-PRETTIER-AUTOFIX-ELSE-IF
  */
 const eslint_1 = require("eslint");
 const require_branch_annotation_1 = __importDefault(require("../../src/rules/require-branch-annotation"));
@@ -289,6 +291,21 @@ if (outer) {
 for (let i = 0; i < 3; i++) {}`,
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
+            {
+                name: "[REQ-PRETTIER-AUTOFIX-ELSE-IF] missing annotations on else-if branch with Prettier-style autofix insertion",
+                code: `if (a) {
+  doA();
+} else if (b) {
+  doB();
+}`,
+                output: `// @story <story-file>.story.md
+if (a) {
+  doA();
+} else if (b) {
+  doB();
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req", "@story", "@req"),
+            },
         ],
     });
     runRule({

package/lib/tests/utils/branch-annotation-catch-insert-position.test.d.ts ADDED Viewed

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

package/lib/tests/utils/branch-annotation-catch-insert-position.test.js ADDED Viewed

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for CatchClause insert position calculation.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-PRETTIER-AUTOFIX
+ */
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+describe("CatchClause insert position (Story 025.0-DEV-CATCH-ANNOTATION-POSITION)", () => {
+    it("[REQ-PRETTIER-AUTOFIX] inserts annotations at the first statement inside the catch body", () => {
+        const lines = [
+            "try {",
+            "  doSomething();",
+            "}",
+            "catch (error) {",
+            "  handleError(error);",
+            "}",
+        ];
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const context = {
+            getSourceCode() {
+                return {
+                    lines,
+                    getCommentsBefore() {
+                        return [];
+                    },
+                    getIndexFromLoc({ line, column }) {
+                        // simple line/column to index mapping for the test: assume each line ends with "\n"
+                        const prefix = lines.slice(0, line - 1).join("\n");
+                        return prefix.length + (line > 1 ? 1 : 0) + column;
+                    },
+                };
+            },
+            report({ fix }) {
+                // immediately invoke the fixer to exercise the insert position
+                if (typeof fix === "function") {
+                    fix(fixer);
+                }
+            },
+        };
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 4 } },
+            body: {
+                type: "BlockStatement",
+                loc: { start: { line: 4 } },
+                body: [
+                    {
+                        type: "ExpressionStatement",
+                        loc: { start: { line: 5 } },
+                    },
+                ],
+            },
+        };
+        const storyFixCountRef = { count: 0 };
+        (0, branch_annotation_helpers_1.reportMissingAnnotations)(context, node, storyFixCountRef);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
+        const [range, text] = fixer.insertTextBeforeRange.mock.calls[0];
+        // ensure we are inserting before the first statement in the catch body (line 5)
+        const expectedIndex = context.getSourceCode().getIndexFromLoc({ line: 5, column: 0 });
+        expect(range).toEqual([expectedIndex, expectedIndex]);
+        // and that the inserted text is prefixed with the inner indentation from line 5
+        expect(text.startsWith("  ")).toBe(true);
+    });
+});

package/lib/tests/utils/branch-annotation-catch-position.test.d.ts ADDED Viewed

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

package/lib/tests/utils/branch-annotation-catch-position.test.js ADDED Viewed

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+function createMockSourceCode(options) {
+    const { lines = [], commentsBefore = [], commentsInside = [] } = options;
+    return {
+        lines,
+        getCommentsBefore() {
+            return commentsBefore;
+        },
+        getCommentsInside(node) {
+            // exercise the code path that passes node.body into getCommentsInside
+            if (node && node.type === "BlockStatement") {
+                return commentsInside;
+            }
+            return [];
+        },
+    };
+}
+describe("gatherBranchCommentText CatchClause behavior (Story 025.0-DEV-CATCH-ANNOTATION-POSITION)", () => {
+    it("[REQ-DUAL-POSITION-DETECTION] prefers before-catch annotations when present", () => {
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [
+                { value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md" },
+                { value: "@req REQ-BRANCH-DETECTION" },
+            ],
+            commentsInside: [
+                { value: "@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md" },
+            ],
+        });
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 5 } },
+            body: { type: "BlockStatement" },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(text).toContain("@req REQ-BRANCH-DETECTION");
+    });
+    it("[REQ-FALLBACK-LOGIC] falls back to inside-catch annotations when before-catch is missing", () => {
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [],
+            commentsInside: [
+                { value: "@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md" },
+                { value: "@req REQ-CATCH-PATH" },
+            ],
+        });
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 10 } },
+            body: { type: "BlockStatement" },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-CATCH-PATH");
+    });
+    it("[REQ-FALLBACK-LOGIC] returns before-catch text when getCommentsInside is not available", () => {
+        const lines = [
+            "try {",
+            "  doSomething();",
+            "}",
+            "catch (error) {",
+            "  // body",
+            "}",
+        ];
+        const sourceCode = {
+            lines,
+            getCommentsBefore() {
+                return [
+                    { value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md" },
+                    { value: "@req REQ-BRANCH-DETECTION" },
+                ];
+            },
+            // intentionally omit getCommentsInside so that the CatchClause path
+            // falls back to the before-catch comments.
+        };
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 4 } },
+            body: { type: "BlockStatement" },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(text).toContain("@req REQ-BRANCH-DETECTION");
+    });
+    it("[REQ-FALLBACK-LOGIC] collects inside-catch comments using line-based fallback when getCommentsInside is unavailable", () => {
+        const lines = [
+            "try {",
+            "  doSomething();",
+            "} catch (error) {",
+            "  // @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md",
+            "  // @req REQ-CATCH-LINE-FALLBACK",
+            "  handleError(error);",
+            "}",
+        ];
+        const sourceCode = {
+            lines,
+            getCommentsBefore() {
+                return [];
+            },
+        };
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 3 } },
+            body: {
+                type: "BlockStatement",
+                loc: { start: { line: 3 }, end: { line: 7 } },
+                body: [],
+            },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-CATCH-LINE-FALLBACK");
+    });
+});

package/lib/tests/utils/req-annotation-detection.test.d.ts ADDED Viewed

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