eslint-plugin-traceability 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.12.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.4...v1.12.0) (2025-12-07)
+# [1.13.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.12.1...v1.13.0) (2025-12-07)
 
 
 ### Features
 
-* accept [@supports](https://github.com/supports) annotations on branches as alternative format ([6773a3a](https://github.com/voder-ai/eslint-plugin-traceability/commit/6773a3ae190e9b9adc605c7d17112f44401e5b24))
+* add no-redundant-annotation rule and scope analyzer utilities ([5dfc6a8](https://github.com/voder-ai/eslint-plugin-traceability/commit/5dfc6a897a986ba5999c933e67a3834d9f237c33))
 
 # Changelog
 

package/lib/src/index.js

@@ -19,6 +19,7 @@ const RULE_NAMES = [
     "valid-req-reference",
     "prefer-implements-annotation",
     "require-test-traceability",
+    "no-redundant-annotation",
 ];
 const rules = {};
 exports.rules = rules;
@@ -156,6 +157,7 @@ const TRACEABILITY_RULE_SEVERITIES = {
     "traceability/valid-story-reference": "error",
     "traceability/valid-req-reference": "error",
     "traceability/require-test-traceability": "error",
+    "traceability/no-redundant-annotation": "warn",
 };
 /**
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md

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

@@ -98,6 +98,46 @@ exports.STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
  * Allowed values for export priority option.
  */
 exports.EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
+/**
+ * Safely execute a reporting operation, swallowing unexpected errors so that
+ * traceability rules never break ESLint runs. When TRACEABILITY_DEBUG=1 is
+ * set in the environment, a diagnostic message is logged to stderr.
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-RESILIENCE
+ */
+function withSafeReporting(label, fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        if (process.env.TRACEABILITY_DEBUG === "1") {
+            // Debug logging only when explicitly enabled for troubleshooting helper failures.
+            console.error(`[traceability] ${label} failed`, error?.message ?? error);
+        }
+    }
+}
+/**
+ * Build the shared ESLint report descriptor for a missing @story annotation.
+ * This keeps the core helpers focused on computing names, targets, and
+ * templates while centralizing the diagnostic wiring.
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ERROR-SPECIFIC
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-RESILIENCE
+ */
+function createMissingStoryReportDescriptor(config) {
+    const { nameNode, name, resolvedTarget, effectiveTemplate, allowFix, createFix, } = config;
+    const baseFix = createFix(resolvedTarget, effectiveTemplate);
+    return {
+        node: nameNode,
+        messageId: "missingStory",
+        data: { name, functionName: name },
+        fix: allowFix ? baseFix : undefined,
+        suggest: [
+            {
+                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
+                fix: baseFix,
+            },
+        ],
+    };
+}
 /**
  * Core helper to report a missing @story annotation for a function-like node.
  * This reporting utility delegates behavior to injected dependencies so that
@@ -111,7 +151,7 @@ exports.EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
  */
 function coreReportMissing(deps, context, sourceCode, config) {
     const { node, target: passedTarget, options = {} } = config;
-    try {
+    withSafeReporting("coreReportMissing", () => {
         if (deps.hasStoryAnnotation(sourceCode, node)) {
             return;
         }
@@ -120,30 +160,15 @@ function coreReportMissing(deps, context, sourceCode, config) {
         const nameNode = deps.getNameNodeForReport(node);
         const { effectiveTemplate, allowFix } = deps.buildTemplateConfig(options);
         const name = functionName;
-        context.report({
-            node: nameNode,
-            messageId: "missingStory",
-            data: { name, functionName: name },
-            fix: allowFix
-                ? deps.createAddStoryFix(resolvedTarget, effectiveTemplate)
-                : undefined,
-            suggest: [
-                {
-                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
-                    fix: deps.createAddStoryFix(resolvedTarget, effectiveTemplate),
-                },
-            ],
-        });
-    }
-    catch (error) {
-        // Intentionally swallow unexpected helper errors so traceability checks never
-        // break lint runs. When TRACEABILITY_DEBUG=1 is set, log a debug message to
-        // help diagnose misbehaving helpers in local development without affecting
-        // normal CI or production usage.
-        if (process.env.TRACEABILITY_DEBUG === "1") {
-            console.error("[traceability] coreReportMissing failed for node", error?.message ?? error);
-        }
-    }
+        context.report(createMissingStoryReportDescriptor({
+            nameNode,
+            name,
+            resolvedTarget,
+            effectiveTemplate,
+            allowFix,
+            createFix: deps.createAddStoryFix,
+        }));
+    });
 }
 /**
  * Core helper to report a missing @story annotation for a method-like node.
@@ -158,37 +183,21 @@ function coreReportMissing(deps, context, sourceCode, config) {
  */
 function coreReportMethod(deps, context, sourceCode, config) {
     const { node, target: passedTarget, options = {} } = config;
-    try {
+    withSafeReporting("coreReportMethod", () => {
         if (deps.hasStoryAnnotation(sourceCode, node)) {
             return;
         }
         const resolvedTarget = passedTarget ?? deps.resolveAnnotationTargetNode(sourceCode, node, null);
         const name = deps.extractName(node);
         const nameNode = (node.key && node.key.type === "Identifier" && node.key) || node;
-        const effectiveTemplate = deps.getAnnotationTemplate(options.annotationTemplateOverride);
-        const allowFix = deps.shouldApplyAutoFix(options.autoFixToggle);
-        context.report({
-            node: nameNode,
-            messageId: "missingStory",
-            data: { name, functionName: name },
-            fix: allowFix
-                ? deps.createMethodFix(resolvedTarget, effectiveTemplate)
-                : undefined,
-            suggest: [
-                {
-                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
-                    fix: deps.createMethodFix(resolvedTarget, effectiveTemplate),
-                },
-            ],
-        });
-    }
-    catch (error) {
-        // Intentionally swallow unexpected helper errors so traceability checks never
-        // break lint runs. When TRACEABILITY_DEBUG=1 is set, log a debug message to
-        // help diagnose misbehaving helpers in local development without affecting
-        // normal CI or production usage.
-        if (process.env.TRACEABILITY_DEBUG === "1") {
-            console.error("[traceability] coreReportMethod failed for node", error?.message ?? error);
-        }
-    }
+        const { effectiveTemplate, allowFix } = deps.buildTemplateConfig(options);
+        context.report(createMissingStoryReportDescriptor({
+            nameNode,
+            name,
+            resolvedTarget,
+            effectiveTemplate,
+            allowFix,
+            createFix: deps.createMethodFix,
+        }));
+    });
 }

package/lib/src/rules/no-redundant-annotation.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/src/rules/no-redundant-annotation.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const branch_annotation_helpers_1 = require("../utils/branch-annotation-helpers");
+const annotation_scope_analyzer_1 = require("../utils/annotation-scope-analyzer");
+/**
+ * ESLint rule to detect redundant traceability annotations on statements
+ * that are already covered by their containing scope.
+ *
+ * This rule focuses on simple, statement-level patterns that the
+ * existing branch and function rules already treat as covered by
+ * surrounding annotations. It treats redundant annotations as
+ * maintainability concerns rather than correctness issues, and is
+ * therefore exposed as a warning-level rule by default.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION REQ-STATEMENT-SIGNIFICANCE REQ-SAFE-REMOVAL REQ-DIFFERENT-REQUIREMENTS REQ-CONFIGURABLE-STRICTNESS REQ-SCOPE-INHERITANCE
+ */
+const DEFAULT_ALWAYS_COVERED_STATEMENTS = [
+    "ReturnStatement",
+    "VariableDeclaration",
+];
+const DEFAULT_STRICTNESS = "moderate";
+const DEFAULT_ALLOW_EMPHASIS_DUPLICATION = false;
+const DEFAULT_MAX_SCOPE_DEPTH = 3;
+function normalizeOptions(raw) {
+    const strictness = raw && typeof raw.strictness === "string"
+        ? raw.strictness
+        : DEFAULT_STRICTNESS;
+    const allowEmphasisDuplication = typeof raw?.allowEmphasisDuplication === "boolean"
+        ? raw.allowEmphasisDuplication
+        : DEFAULT_ALLOW_EMPHASIS_DUPLICATION;
+    const maxScopeDepth = typeof raw?.maxScopeDepth === "number" && raw.maxScopeDepth > 0
+        ? raw.maxScopeDepth
+        : DEFAULT_MAX_SCOPE_DEPTH;
+    const alwaysCovered = Array.isArray(raw?.alwaysCovered)
+        ? raw.alwaysCovered
+        : Array.from(DEFAULT_ALWAYS_COVERED_STATEMENTS);
+    return {
+        strictness,
+        allowEmphasisDuplication,
+        maxScopeDepth,
+        alwaysCovered,
+    };
+}
+/**
+ * Compute the story/requirement pairs for annotations that apply to the
+ * given scope node.
+ *
+ * For branch scopes we reuse the same comment-gathering helper used by
+ * the require-branch-annotation rule so that REQ-SCOPE-INHERITANCE
+ * aligns with existing behavior.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE
+ */
+function getScopePairs(context, scopeNode, parent) {
+    const sourceCode = context.getSourceCode();
+    // Branch-style scope: use the branch helpers to collect comment text.
+    if (branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES.includes(scopeNode.type)) {
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent);
+        return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
+    }
+    // Function-like scopes: collect from JSDoc and leading/before comments
+    const FUNCTION_LIKE_TYPES = new Set([
+        "FunctionDeclaration",
+        "FunctionExpression",
+        "ArrowFunctionExpression",
+        "MethodDefinition",
+        "TSDeclareFunction",
+        "TSMethodSignature",
+    ]);
+    const comments = [];
+    if (FUNCTION_LIKE_TYPES.has(scopeNode.type)) {
+        const jsdoc = sourceCode.getJSDocComment
+            ? sourceCode.getJSDocComment(scopeNode)
+            : null;
+        const before = sourceCode.getCommentsBefore
+            ? sourceCode.getCommentsBefore(scopeNode) || []
+            : [];
+        if (jsdoc) {
+            comments.push(jsdoc);
+        }
+        if (Array.isArray(scopeNode.leadingComments)) {
+            comments.push(...scopeNode.leadingComments);
+        }
+        comments.push(...before);
+        return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(comments);
+    }
+    // Fallback: inspect JSDoc and leading comments around the scope node.
+    const jsdoc = sourceCode.getJSDocComment
+        ? sourceCode.getJSDocComment(scopeNode)
+        : null;
+    const before = sourceCode.getCommentsBefore
+        ? sourceCode.getCommentsBefore(scopeNode) || []
+        : [];
+    if (jsdoc) {
+        comments.push(jsdoc);
+    }
+    if (Array.isArray(scopeNode.leadingComments)) {
+        comments.push(...scopeNode.leadingComments);
+    }
+    comments.push(...before);
+    return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(comments);
+}
+/**
+ * Collect the comments directly associated with a statement node.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-STATEMENT-SIGNIFICANCE REQ-SCOPE-ANALYSIS
+ */
+function getStatementComments(context, node) {
+    const sourceCode = context.getSourceCode();
+    const comments = [];
+    if (sourceCode.getCommentsBefore) {
+        comments.push(...(sourceCode.getCommentsBefore(node) || []));
+    }
+    if (Array.isArray(node.leadingComments)) {
+        comments.push(...node.leadingComments);
+    }
+    return comments;
+}
+/**
+ * Debug helper for logging scope-level pairs in TRACEABILITY_DEBUG mode.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS
+ */
+function debugScopePairs(scopeNode, scopePairs) {
+    if (process.env.TRACEABILITY_DEBUG !== "1") {
+        return;
+    }
+    console.log("[no-redundant-annotation] Scope node type=%s pairs=%o", scopeNode && scopeNode.type, Array.from(scopePairs));
+}
+/**
+ * Analyze a block's statements and report redundant traceability annotations.
+ *
+ * This helper encapsulates the iteration and reporting logic so that the
+ * BlockStatement visitor remains small and focused on scope setup.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-STATEMENT-SIGNIFICANCE
+ */
+function reportRedundantAnnotationsInBlock(context, blockNode, scopePairs, options) {
+    const statements = Array.isArray(blockNode.body) ? blockNode.body : [];
+    if (statements.length === 0)
+        return;
+    for (const stmt of statements) {
+        if (!(0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES)) {
+            continue;
+        }
+        const stmtComments = getStatementComments(context, stmt);
+        if (stmtComments.length === 0) {
+            continue;
+        }
+        const stmtPairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(stmtComments);
+        if (process.env.TRACEABILITY_DEBUG === "1") {
+            console.log("[no-redundant-annotation] Statement type=%s eligible=%s commentCount=%d pairs=%o", stmt && stmt.type, (0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES), stmtComments.length, Array.from(stmtPairs));
+        }
+        if (stmtPairs.size === 0) {
+            continue;
+        }
+        if (!(0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
+            continue;
+        }
+        // At this point the statement-level annotations are fully
+        // covered by the parent scope and therefore redundant.
+        for (const comment of stmtComments) {
+            const commentText = typeof comment.value === "string" ? comment.value : "";
+            if (!/@story\b|@req\b|@supports\b/.test(commentText)) {
+                continue;
+            }
+            const [removalStart, removalEnd] = (0, annotation_scope_analyzer_1.getCommentRemovalRange)(comment, context.getSourceCode());
+            context.report({
+                node: stmt,
+                messageId: "redundantAnnotation",
+                fix(fixer) {
+                    return fixer.removeRange([removalStart, removalEnd]);
+                },
+            });
+        }
+    }
+}
+const rule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Detect and remove redundant traceability annotations already covered by containing scope",
+            recommended: false,
+        },
+        fixable: "code",
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    strictness: {
+                        enum: ["strict", "moderate", "permissive"],
+                    },
+                    allowEmphasisDuplication: {
+                        type: "boolean",
+                    },
+                    maxScopeDepth: {
+                        type: "number",
+                        minimum: 1,
+                    },
+                    alwaysCovered: {
+                        type: "array",
+                        items: { type: "string" },
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            /**
+             * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-CLEAR-MESSAGES REQ-SAFE-REMOVAL
+             */
+            redundantAnnotation: "Annotation on this statement is redundant; it is already covered by its containing scope.",
+        },
+    },
+    create(context) {
+        const options = normalizeOptions(context.options[0]);
+        return {
+            // @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL
+            BlockStatement(node) {
+                const parent = node.parent;
+                const scopeNode = parent;
+                if (process.env.TRACEABILITY_DEBUG === "1") {
+                    console.log("[no-redundant-annotation] BlockStatement parent=%s statements=%d", parent && parent.type, Array.isArray(node.body) ? node.body.length : 0);
+                }
+                const scopePairs = getScopePairs(context, scopeNode, scopeNode?.parent);
+                debugScopePairs(scopeNode, scopePairs);
+                if (scopePairs.size === 0)
+                    return;
+                reportRedundantAnnotationsInBlock(context, node, scopePairs, options);
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/src/utils/annotation-scope-analyzer.d.ts

@@ -0,0 +1,107 @@
+import type { Rule } from "eslint";
+/**
+ * Shared types and helpers for redundant-annotation detection.
+ *
+ * These utilities focus on parsing traceability annotations from comment
+ * text and computing relationships between "scope" coverage and
+ * statement-level annotations. They are intentionally small, pure
+ * functions so that the ESLint rule can delegate most of its logic
+ * here while keeping its own create/visitor code shallow.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION
+ */
+export declare const EXPECTED_RANGE_LENGTH = 2;
+export type Strictness = "strict" | "moderate" | "permissive";
+export interface RedundancyRuleOptions {
+    strictness: Strictness;
+    allowEmphasisDuplication: boolean;
+    maxScopeDepth: number;
+    alwaysCovered: readonly string[];
+}
+/**
+ * Canonical representation of a single story+requirement pair.
+ *
+ * The key form `"<story>|<req>"` lets us compare pairs across scopes
+ * without repeatedly allocating compound objects.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS
+ */
+export type StoryReqKey = string;
+/**
+ * Build a canonical key for a story/requirement pair.
+ *
+ * Empty story or requirement components are normalized to the empty
+ * string so that comparisons remain stable even when some annotations
+ * omit one side (for example, malformed or story-less @req lines).
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS
+ */
+export declare function toStoryReqKey(storyPath: string | null, reqId: string): StoryReqKey;
+/**
+ * Extract story/requirement pairs from a snippet of comment text.
+ *
+ * Supported patterns:
+ * - `@story <path>` followed by one or more `@req <ID>` lines.
+ * - `@supports <path> <REQ-ID-1> <REQ-ID-2> ...` where each `REQ-*`
+ *   token is treated as a separate pair bound to the same story path.
+ *
+ * The parser is intentionally conservative: it only creates pairs when
+ * it can confidently associate a requirement identifier with a story
+ * path. This avoids false positives in REQ-DIFFERENT-REQUIREMENTS by
+ * ensuring we never conflate different requirement IDs.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS
+ */
+export declare function extractStoryReqPairsFromText(text: string): Set<StoryReqKey>;
+/**
+ * Extract story/requirement pairs from a list of ESLint comment nodes.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION
+ */
+export declare function extractStoryReqPairsFromComments(comments: any[]): Set<StoryReqKey>;
+/**
+ * Determine whether all story/requirement pairs in `child` are already
+ * covered by `parent`.
+ *
+ * This implements the core notion of redundancy: if a statement-level
+ * annotation only repeats the exact same story+requirement pairs that
+ * are already declared on its containing scope, it does not add any
+ * new traceability information.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS REQ-SCOPE-INHERITANCE
+ */
+export declare function arePairsFullyCovered(child: Set<StoryReqKey>, parent: Set<StoryReqKey>): boolean;
+/**
+ * Decide whether a given statement node type should be considered
+ * "simple" or "significant" for redundancy detection, based on the
+ * configured strictness and alwaysCovered lists.
+ *
+ * - In `strict` mode, all non-branch statements are eligible.
+ * - In `moderate` mode (default), only statement types listed in
+ *   `alwaysCovered` plus bare expression statements are treated as
+ *   candidates for redundancy.
+ * - In `permissive` mode, only `alwaysCovered` types are considered.
+ *
+ * This keeps REQ-STATEMENT-SIGNIFICANCE and REQ-CONFIGURABLE-STRICTNESS
+ * aligned with the story's configuration model.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS
+ */
+export declare function isStatementEligibleForRedundancy(node: any, options: RedundancyRuleOptions, branchTypes: readonly string[]): boolean;
+/**
+ * Compute the character range that should be removed when auto-fixing a
+ * redundant annotation comment.
+ *
+ * The implementation is conservative to satisfy REQ-SAFE-REMOVAL:
+ *
+ * - When the comment occupies its own line (only whitespace before the
+ *   comment token), the removal range is expanded to include that
+ *   leading whitespace and the trailing newline, so the entire line is
+ *   removed.
+ * - When there is other code before the comment on the same line, only
+ *   the comment text itself is removed, leaving surrounding code and
+ *   whitespace intact.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL
+ */
+export declare function getCommentRemovalRange(comment: any, sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>): [number, number];