eslint-plugin-traceability 1.19.2 → 1.19.4

package/lib/tests/utils/branch-annotation-helpers.test.js

@@ -45,14 +45,12 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
         });
     });
     it("should gather SwitchCase comment text via gatherBranchCommentText (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
-        // Fake SourceCode-like object with lines aligned to PRE_COMMENT_OFFSET logic
         const sourceCode = {
-            lines: [
-                "// @story first part",
-                "// continuation second part",
-                "case 1:",
-            ],
-            getCommentsBefore: () => [],
+            lines: [],
+            getCommentsBefore: jest.fn().mockReturnValue([
+                { value: "@story first part" },
+                { value: "@req REQ-FIRST" },
+            ]),
             getText: jest.fn(),
         };
         // SwitchCase-like node with loc.start.line corresponding to "case 1:" line (line 3)
@@ -64,8 +62,7 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
             },
         };
         const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, switchCaseNode);
-        // Expect combined text using space separator and preserving leading //
-        expect(text).toBe("// @story first part // continuation second part");
+        expect(text).toBe("@story first part @req REQ-FIRST");
     });
     it("should gather comment text for CatchClause and loop nodes via gatherBranchCommentText (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
         // CatchClause: comments come from getCommentsBefore when beforeText already contains @story
@@ -191,6 +188,50 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
         expect(insideText).toContain("@req REQ-CATCH-INSIDE");
         expect(insideText).not.toContain("before-catch should be ignored");
     });
+    it("[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] uses inside-switch comments when annotationPlacement is 'inside' and ignores before-case annotations", () => {
+        const sourceCode = {
+            lines: [
+                "// @story before-switch should be ignored in inside mode",
+                "switch (value) {",
+                "  case 'a': {",
+                "    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md",
+                "    // @req REQ-SWITCH-INSIDE",
+                "    doSomething();",
+                "  }",
+                "}",
+            ],
+            getCommentsBefore: jest
+                .fn()
+                .mockReturnValue([
+                { value: "@story before-switch should be ignored in inside mode" },
+            ]),
+        };
+        const switchCaseNode = {
+            type: "SwitchCase",
+            loc: {
+                start: { line: 3, column: 2 },
+                end: { line: 7, column: 4 },
+            },
+            consequent: [
+                {
+                    type: "BlockStatement",
+                    loc: {
+                        start: { line: 3, column: 16 },
+                        end: { line: 7, column: 4 },
+                    },
+                },
+            ],
+        };
+        const parent = {
+            type: "SwitchStatement",
+            discriminant: { type: "Identifier", name: "value" },
+            cases: [switchCaseNode],
+        };
+        const insideText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, switchCaseNode, parent, "inside");
+        expect(insideText).toContain("@story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md");
+        expect(insideText).toContain("@req REQ-SWITCH-INSIDE");
+        expect(insideText).not.toContain("before-switch should be ignored");
+    });
 });
 /**
  * Tests for annotationPlacement wiring at helper level
@@ -311,4 +352,110 @@ describe("gatherBranchCommentText annotationPlacement wiring (Story 028.0-DEV-AN
         expect(insideText).not.toContain("REQ-BEFORE-ELSE");
         expect(insideText).not.toContain("docs/stories/026.0-DEV-BRANCH-ANNOTATIONS-ELSE-BRANCHES.story.md");
     });
+    it("[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] honors configured placement for TryStatement branches in try/finally patterns", () => {
+        const sourceCode = {
+            lines: [
+                "function demoTry() {", // 1
+                "  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md", // 2 (before try)
+                "  // @req REQ-BEFORE-TRY", // 3
+                "  try {", // 4
+                "    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md", // 5 (inside try)
+                "    // @req REQ-TRY-INSIDE", // 6
+                "    doWork();", // 7
+                "  } finally {", // 8
+                "    cleanup();", // 9
+                "  }", // 10
+                "}", // 11
+            ],
+            getCommentsBefore: jest.fn().mockImplementation((node) => {
+                if (node && node.loc && node.loc.start && node.loc.start.line === 4) {
+                    return [
+                        {
+                            value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md",
+                        },
+                        { value: "@req REQ-BEFORE-TRY" },
+                    ];
+                }
+                return [];
+            }),
+        };
+        const tryNode = {
+            type: "TryStatement",
+            loc: {
+                start: { line: 4, column: 2 },
+                end: { line: 9, column: 3 },
+            },
+            block: {
+                type: "BlockStatement",
+                loc: {
+                    start: { line: 4, column: 8 },
+                    end: { line: 7, column: 3 },
+                },
+            },
+            handler: null,
+            finalizer: {
+                type: "BlockStatement",
+                loc: {
+                    start: { line: 8, column: 12 },
+                    end: { line: 9, column: 3 },
+                },
+            },
+        };
+        const parent = {
+            type: "BlockStatement",
+            body: [tryNode],
+        };
+        const beforeText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, tryNode, parent, "before");
+        expect(beforeText).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(beforeText).toContain("@req REQ-BEFORE-TRY");
+        expect(beforeText).not.toContain("REQ-TRY-INSIDE");
+        const insideText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, tryNode, parent, "inside");
+        expect(insideText).toContain("@story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md");
+        expect(insideText).toContain("@req REQ-TRY-INSIDE");
+        expect(insideText).not.toContain("REQ-BEFORE-TRY");
+    });
+    it("[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] honors before-case annotations for SwitchCase in default placement mode", () => {
+        const sourceCode = {
+            lines: [
+                "// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md",
+                "// @req REQ-SWITCH-BEFORE",
+                "switch (value) {",
+                "  case 'a':",
+                "    doSomething();",
+                "}",
+            ],
+            getCommentsBefore: jest
+                .fn()
+                .mockReturnValue([
+                {
+                    value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md",
+                },
+                { value: "@req REQ-SWITCH-BEFORE" },
+            ]),
+        };
+        const switchCaseNode = {
+            type: "SwitchCase",
+            loc: {
+                start: { line: 4, column: 2 },
+                end: { line: 5, column: 18 },
+            },
+            consequent: [
+                {
+                    type: "ExpressionStatement",
+                    loc: {
+                        start: { line: 5, column: 4 },
+                        end: { line: 5, column: 18 },
+                    },
+                },
+            ],
+        };
+        const parent = {
+            type: "SwitchStatement",
+            discriminant: { type: "Identifier", name: "value" },
+            cases: [switchCaseNode],
+        };
+        const beforeText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, switchCaseNode, parent, "before");
+        expect(beforeText).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(beforeText).toContain("@req REQ-SWITCH-BEFORE");
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.19.2",
+  "version": "1.19.4",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",

package/user-docs/api-reference.md

@@ -86,13 +86,14 @@ function initAuth() {
 
 ### traceability/require-branch-annotation
 
-Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have traceability coverage, typically via a single `@supports` line, while still accepting legacy `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`.
+Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have traceability coverage, typically via a single `@supports` line, while still accepting legacy `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`. The rule supports a configurable placement mode for branch annotations via `annotationPlacement: "before" | "inside"`, defaulting to `"before"` for backward compatibility.
 
 For most branches, the rule looks for annotations in comments immediately preceding the branch keyword (for example, the line above an `if` or `for` statement). For `catch` clauses and `else if` branches, the rule is formatter-aware and accepts annotations in additional positions that common formatters like Prettier use when they reflow code.
 
 Options:
 
 - `branchTypes` (string[], optional) – AST node types that are treated as significant branches for annotation enforcement. Allowed values: "IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement". Default: ["IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"]. If an invalid branch type is provided, the rule reports a configuration error for each invalid value.
+- `annotationPlacement` ("before" | "inside", optional) – Controls whether the rule looks for annotations immediately before branches (`"before"`, the default and backward-compatible behavior) or requires annotations as the first comment lines inside branch bodies where supported (`"inside"`). When set to `"inside"`, the rule prefers comments at the top of the block bodies for simple `if`/`else if` branches, loops, `catch` clauses, and `try` blocks, while continuing to treat any existing before-branch comments as diagnostics in that mode.
 
 Behavior notes:
 
@@ -109,6 +110,11 @@ Behavior notes:
   - When annotations appear in more than one of these locations, the rule prefers the comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body. This precedence is designed to closely mirror real-world formatter behavior and matches the formatter-aware scenarios described in stories 025.0 and 026.0.
   - When auto-fixing missing annotations on an `else if` branch, the rule inserts placeholder comments as the first comment-only line inside the consequent block body (just after the opening `{`), which is a stable location under Prettier and similar formatters. As with catch clauses, a single `@supports` annotation placed in any of these accepted locations is treated as equivalent to having both `@story` and `@req` comments for that branch, with deep format and existence checks delegated to the other validation rules.
 
+Placement modes:
+
+- `"before"` mode preserves the existing semantics described above, including the dual-position behavior for `catch` and `else if` branches where comments immediately before the branch and the first comment-only lines inside the block are both acceptable and validated according to their existing precedence rules.
+- `"inside"` mode standardizes on the first comment-only lines inside supported branch blocks (`if`/`else if`, loops, `catch`, and `try`) for validation and auto-fix insertion. This placement is designed to work well with Prettier and other formatters, while the current implementation still treats many before-branch annotations as needing migration and may, in corner cases where it cannot confidently rewrite placement, insert new placeholder comments above the branch rather than moving existing ones.
+
 For a concrete illustration of how these rules interact with Prettier, see the formatter-aware if/else/else-if example in [user-docs/examples.md](examples.md) (section **6. Branch annotations with if/else/else-if and Prettier**), which shows both the hand-written and formatted code that the rule considers valid.
 
 These behaviors are intentionally limited to `catch` clauses and `else if` branches; other branch types (plain `if`, `else`, loops, and `switch` cases) continue to use the simpler "comments immediately before the branch" association model for both validation and auto-fix placement.

package/user-docs/migration-guide.md

@@ -354,6 +354,46 @@ The full API reference documents all options, but the most important knobs for m
 
 For most teams, the defaults in the recommended preset are a good starting point; you can then tune these options incrementally as your traceability style and `@supports` usage stabilize.
 
+### 3.4 Inside-brace branch annotation placement (optional)
+
+Story 028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION introduces an **inside-brace** placement standard for branch annotations. Instead of placing annotations directly above a branch, you can configure `traceability/require-branch-annotation` to look for annotations as the first comment-only lines **inside** each block body.
+
+The feature is controlled by the `annotationPlacement` option on `require-branch-annotation`:
+
+```js
+// eslint.config.js (flat config example)
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  traceability.configs.recommended,
+  {
+    rules: {
+      "traceability/require-branch-annotation": [
+        "error",
+        {
+          annotationPlacement: "inside", // "before" (default) or "inside"
+        },
+      ],
+    },
+  },
+];
+```
+
+With `annotationPlacement: "inside"`, the rule expects annotations in these locations:
+
+- `if` / `else if` / `else`: first comment-only lines inside the `{ ... }` block.
+- Loops: first comment-only lines inside the loop body.
+- `try` / `catch` / `finally`: first comment-only lines inside the corresponding block body.
+- `switch` cases: first comment-only lines inside the `case` body when it is a block (`case 'a': { ... }`).
+
+Before-brace annotations are still honored when you leave `annotationPlacement` at the default value (`"before"`), so you can migrate gradually:
+
+1. **Start in default mode** — keep `annotationPlacement` unspecified (or set to `"before"`) and continue using your existing `// @story` / `// @req` comments above branches.
+2. **Introduce inside-brace style for new code** — when adding or refactoring branches, place annotations on the first comment-only line inside the block body. This layout plays nicely with Prettier and is what the rule’s auto-fix uses for `if`/`else if` and similar branches.
+3. **Opt-in to `annotationPlacement: "inside"`** — once your codebase is mostly using inside-brace annotations, enable the option. Branches that still rely only on before-brace comments will be reported as missing annotations in inside mode, and the rule’s autofix can insert placeholders at the correct inside location to help you complete the migration.
+
+The default configuration in 1.x keeps `annotationPlacement` at `"before"` for backward compatibility, so existing projects do not need to change anything unless they want the new inside-brace behavior.
+
 ## 4. Test and Validate
 
 Run your test suite to confirm everything passes: