eslint-plugin-traceability 1.19.4 → 1.20.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.19.4](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.3...v1.19.4) (2025-12-18)
+# [1.20.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.4...v1.20.0) (2025-12-18)
 
 
-### Bug Fixes
+### Features
 
-* migrate before-brace annotations into inside-brace placement ([c8c381d](https://github.com/voder-ai/eslint-plugin-traceability/commit/c8c381d5f5fbd39fdb626e9dd6fe2dd837bffb53))
+* extend branch placement standard docs and helpers ([ae05a52](https://github.com/voder-ai/eslint-plugin-traceability/commit/ae05a5232b724060f7b1baae9a6be6eedf466617))
 
 # Changelog
 

package/README.md

@@ -123,7 +123,9 @@ Traceability annotations are typically placed immediately adjacent to the code t
   - As JSDoc blocks immediately preceding the function, or
   - As line comments placed directly before the function declaration or expression.
 
-  This placement is stable and supported for all current versions. Future versions may introduce an **inside-brace** placement mode for function bodies (similar to branch blocks) to align function annotations with the branch-level `"inside"` standard.
+  Function-level rules now support the same placement configuration model as branches:
+  - By default, annotations are still placed immediately before the function (JSDoc or line comments).
+  - When you configure `annotationPlacement: "inside"` on `traceability/require-story-annotation`, the rule prefers annotations as the first comment-only lines inside the function or method body, mirroring the branch-level inside-brace standard from Story 028.0. Declaration-only shapes such as `TSDeclareFunction` and `TSMethodSignature` remain before-function only, since they have no executable body.
 
 For full configuration details and migration guidance between placement styles, see:
 

package/lib/src/rules/helpers/require-story-core.js

@@ -139,6 +139,10 @@ function createMissingStoryReportDescriptor(config) {
         ],
     };
 }
+function resolveAnnotationPlacement(options) {
+    const raw = options?.annotationPlacement;
+    return raw === "inside" || raw === "before" ? raw : "before";
+}
 /**
  * Core helper to report a missing @story annotation for a function-like node.
  * This reporting utility delegates behavior to injected dependencies so that
@@ -153,6 +157,11 @@ function createMissingStoryReportDescriptor(config) {
 function coreReportMissing(deps, context, sourceCode, config) {
     const { node, target: passedTarget, options = {} } = config;
     withSafeReporting("coreReportMissing", () => {
+        const annotationPlacement = resolveAnnotationPlacement(options);
+        if (typeof deps.hasStoryAnnotationWithPlacement === "function" &&
+            deps.hasStoryAnnotationWithPlacement(sourceCode, node, annotationPlacement)) {
+            return;
+        }
         if (deps.hasStoryAnnotation(sourceCode, node)) {
             return;
         }

package/lib/src/rules/helpers/require-story-helpers.d.ts

@@ -53,6 +53,7 @@ declare function leadingCommentsHasStory(node: any): boolean;
  * @req REQ-ANNOTATION-REQUIRED - Detect existing story annotations in JSDoc or comments
  */
 declare function hasStoryAnnotation(sourceCode: any, node: any): boolean;
+declare const hasStoryAnnotationWithPlacement: typeof hasStoryAnnotation;
 /**
  * Determine AST node where annotation should be inserted
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -84,4 +85,4 @@ declare function reportMethod(context: Rule.RuleContext, sourceCode: any, config
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED
  */
-export { STORY_PATH, getAnnotationTemplate, shouldApplyAutoFix, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, extractName, resolveTargetNode, shouldProcessNode, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, reportMissing, reportMethod, };
+export { STORY_PATH, getAnnotationTemplate, shouldApplyAutoFix, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, hasStoryAnnotationWithPlacement, getNodeName, extractName, resolveTargetNode, shouldProcessNode, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, reportMissing, reportMethod, };

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.getNodeName = exports.STORY_PATH = void 0;
+exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.getNodeName = exports.hasStoryAnnotationWithPlacement = exports.STORY_PATH = void 0;
 exports.getAnnotationTemplate = getAnnotationTemplate;
 exports.shouldApplyAutoFix = shouldApplyAutoFix;
 exports.isExportedNode = isExportedNode;
@@ -220,6 +220,9 @@ function hasStoryAnnotation(sourceCode, node) {
     }
     return false;
 }
+// Placement-aware alias reserved for future inside-brace function placement.
+const hasStoryAnnotationWithPlacement = hasStoryAnnotation;
+exports.hasStoryAnnotationWithPlacement = hasStoryAnnotationWithPlacement;
 /**
  * Determine AST node where annotation should be inserted
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md

package/lib/src/rules/require-req-annotation.d.ts

@@ -6,6 +6,10 @@
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of which exports are checked
  * @req REQ-EXPORT-PRIORITY - Allow configuration of export priority behavior
+ *
+ * Note: This rule accepts annotationPlacement for configuration parity with
+ * require-story-annotation, but currently still requires annotations before
+ * the function (no inside-function support yet).
  */
 import type { Rule } from "eslint";
 declare const rule: Rule.RuleModule;

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

@@ -39,6 +39,9 @@ const rule = {
                     exportPriority: {
                         enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES,
                     },
+                    annotationPlacement: {
+                        enum: ["before", "inside"],
+                    },
                 },
                 additionalProperties: false,
             },

package/lib/src/rules/require-story-annotation.d.ts

@@ -17,6 +17,10 @@ import type { Rule } from "eslint";
 /**
  * ESLint rule to require @story annotations on functions/methods.
  *
+ * This rule participates in Story 028.0 placement standardization by supporting
+ * configurable annotation placement, including inside-brace function annotations
+ * when configured.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md

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

@@ -5,6 +5,10 @@ const require_story_helpers_1 = require("./helpers/require-story-helpers");
 /**
  * ESLint rule to require @story annotations on functions/methods.
  *
+ * This rule participates in Story 028.0 placement standardization by supporting
+ * configurable annotation placement, including inside-brace function annotations
+ * when configured.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md

package/lib/src/utils/function-annotation-helpers.d.ts

@@ -0,0 +1,23 @@
+import type { Rule } from "eslint";
+/**
+ * Determine whether a function-like node can support inside-brace
+ * placement semantics. Only nodes with a concrete BlockStatement body are
+ * eligible; TypeScript declarations and signature-only nodes are
+ * intentionally excluded.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES
+ */
+export declare function supportsInsidePlacementForFunction(node: any): boolean;
+/**
+ * Gather the concatenated comment text from the first contiguous
+ * comment-only lines inside a function body. When no such comments are
+ * present or the node has no block body, an empty string is returned.
+ *
+ * This mirrors the branch helpers' behaviour for inside-brace placement
+ * (for example, simple if-statements and switch cases) so that
+ * function-level rules can share the same mental model: annotations live
+ * on the first comment-only line(s) inside the body braces.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-ALL-BLOCK-TYPES
+ */
+export declare function getFunctionInsideBodyCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;

package/lib/src/utils/function-annotation-helpers.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportsInsidePlacementForFunction = supportsInsidePlacementForFunction;
+exports.getFunctionInsideBodyCommentText = getFunctionInsideBodyCommentText;
+const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+/**
+ * Helpers for determining function-body annotation placement.
+ *
+ * These utilities are shared between the function-level traceability rules
+ * (require-story-annotation, require-req-annotation) so they can honour the
+ * same "inside" placement semantics used by branch rules when
+ * `annotationPlacement: "inside"` is configured.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+/**
+ * Locate the BlockStatement that represents the executable body of a
+ * function-like construct. Returns null when the node has no block body
+ * (for example, TypeScript declarations or arrow functions with
+ * expression bodies).
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES
+ */
+function getFunctionBodyBlock(node) {
+    if (!node || typeof node.type !== "string") {
+        return null;
+    }
+    if (node.type === "FunctionDeclaration" ||
+        node.type === "FunctionExpression" ||
+        node.type === "ArrowFunctionExpression") {
+        const body = node.body;
+        return body && body.type === "BlockStatement" ? body : null;
+    }
+    if (node.type === "MethodDefinition") {
+        const value = node.value;
+        if (value && value.type === "FunctionExpression") {
+            const body = value.body;
+            return body && body.type === "BlockStatement" ? body : null;
+        }
+    }
+    return null;
+}
+/**
+ * Determine whether a function-like node can support inside-brace
+ * placement semantics. Only nodes with a concrete BlockStatement body are
+ * eligible; TypeScript declarations and signature-only nodes are
+ * intentionally excluded.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES
+ */
+function supportsInsidePlacementForFunction(node) {
+    return !!getFunctionBodyBlock(node);
+}
+/**
+ * Gather the concatenated comment text from the first contiguous
+ * comment-only lines inside a function body. When no such comments are
+ * present or the node has no block body, an empty string is returned.
+ *
+ * This mirrors the branch helpers' behaviour for inside-brace placement
+ * (for example, simple if-statements and switch cases) so that
+ * function-level rules can share the same mental model: annotations live
+ * on the first comment-only line(s) inside the body braces.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-ALL-BLOCK-TYPES
+ */
+function getFunctionInsideBodyCommentText(sourceCode, node) {
+    const block = getFunctionBodyBlock(node);
+    if (!block ||
+        !block.loc ||
+        !block.loc.start ||
+        !block.loc.end ||
+        typeof block.loc.start.line !== "number" ||
+        typeof block.loc.end.line !== "number") {
+        return "";
+    }
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (typeof getCommentsInside === "function") {
+        try {
+            const insideComments = getCommentsInside(block) || [];
+            const insideText = insideComments
+                .filter((c) => c && typeof c.value === "string")
+                .map((c) => c.value)
+                .join(" ");
+            if (insideText) {
+                return insideText;
+            }
+        }
+        catch {
+            // Fall through to the line-based fallback when structured comment
+            // retrieval is unavailable or fails.
+        }
+    }
+    const lines = sourceCode.lines;
+    if (!Array.isArray(lines)) {
+        return "";
+    }
+    const startIndex = block.loc.start.line - 1;
+    const endIndex = block.loc.end.line - 1;
+    const insideText = (0, branch_annotation_helpers_1.scanCommentLinesInRange)(lines, startIndex + 1, endIndex);
+    return insideText || "";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.19.4",
+  "version": "1.20.0",
   "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

@@ -26,7 +26,7 @@ For function-level traceability, the plugin exposes a unified rule and two legac
 - `traceability/require-traceability` is the **canonical function-level rule** for new configurations. It ensures functions and methods have both story coverage and requirement coverage, and it accepts either `@supports` (preferred) or legacy `@story` / `@req` annotations.
 - `traceability/require-story-annotation` and `traceability/require-req-annotation` are **backward-compatible aliases** that focus on the story and requirement aspects separately. They are retained for existing configurations and share the same underlying implementation model as the unified rule, but new ESLint configs should normally rely on `traceability/require-traceability` rather than enabling these legacy keys directly.
 
-All three rule keys can still be configured individually if you need fine-grained control (for example, to tune severities separately), but the recommended and strict presets enable `traceability/require-traceability` by default and keep the legacy keys primarily for projects that adopted them before the unified rule existed.
+All three rule keys can still be configured individually if you need fine-grained control (for example, to tune severities separately), but the recommended and strict presets enable `traceability/require-traceability` by default and keep the legacy keys primarily for projects that adopted them before the unified rule existed. When the underlying function rules are configured with `annotationPlacement: "inside"`, the unified `require-traceability` rule honours inside-brace placement for function and method bodies in the same formatter-aware way that `require-branch-annotation` handles branches.
 
 ### traceability/require-traceability
 
@@ -44,6 +44,7 @@ Options:
 - `methodAnnotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations for class methods and TypeScript method signatures. When omitted or blank, falls back to `annotationTemplate` if provided, otherwise the built-in template.
 - `autoFix` (boolean, optional) – When set to `false`, disables all automatic fix behavior for this rule while retaining its suggestions and diagnostics. When omitted or `true`, the rule behaves as before, inserting placeholder annotations in `--fix` mode.
 - `excludeTestCallbacks` (boolean, optional) – When `true` (default), excludes anonymous arrow functions that are direct callbacks to common test framework functions (for example, Jest/Mocha/Vitest `describe`/`it`/`test`/`beforeEach`/`afterEach`/`beforeAll`/`afterAll`, plus focused/skipped/concurrent variants such as `fdescribe`, `xdescribe`, `fit`, `xit`, `test.concurrent`, `describe.concurrent`) from function-level annotation requirements. This assumes those test files are already covered by file-level `@supports` annotations and `traceability/require-test-traceability`. When set to `false`, these callbacks are treated like any other arrow function and must be annotated when in-scope.
+- `annotationPlacement` ("before" | "inside", optional) – Controls whether the rule looks for annotations immediately before functions (`"before"`, the default and backward-compatible behaviour) or allows annotations as the first comment-only lines inside function and method bodies (`"inside"`). In inside mode, the rule continues to treat TypeScript declarations and signature-only nodes (such as `TSDeclareFunction` and `TSMethodSignature`) as before-function only, since they have no executable body.
 
 Default Severity: `error`
 Example:
@@ -70,6 +71,7 @@ Options:
 
 - `scope` (string[], optional) – Controls which function-like node types are required to have @req annotations. Allowed values: "FunctionDeclaration", "FunctionExpression", "MethodDefinition", "TSDeclareFunction", "TSMethodSignature". Default: ["FunctionDeclaration", "FunctionExpression", "MethodDefinition", "TSDeclareFunction", "TSMethodSignature"].
 - `exportPriority` ("all" | "exported" | "non-exported", optional) – Controls whether the rule checks all functions, only exported ones, or only non-exported ones. Default: "all".
+- `annotationPlacement` ("before" | "inside", optional) – Accepted for configuration parity with `require-story-annotation`; requirement annotations are still evaluated using before-function comments and JSDoc today, so `"inside"` does not change behaviour yet.
 
 Default Severity: `error`
 Example (with both `@story` and `@req`, as typically used when both rules are enabled):
@@ -113,7 +115,7 @@ Behavior notes:
 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.
+- `"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. Story `028.0-DEV-FUNCTION-PLACEMENT` also extends this inside-brace standard to function and method bodies via `require-story-annotation` when configured, so projects can apply a single inside-brace rule consistently to both branches and functions.
 
 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.