eslint-plugin-traceability 1.21.1 → 1.22.0

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

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAnonymousArrowFunction = isAnonymousArrowFunction;
+exports.isNestedFunction = isNestedFunction;
+exports.isEffectivelyAnonymousFunction = isEffectivelyAnonymousFunction;
+exports.isExportedNode = isExportedNode;
+exports.resolveTargetNode = resolveTargetNode;
+exports.resolveAnnotationTargetNode = resolveAnnotationTargetNode;
+/**
+ * Node classification utilities for require-story rule
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - File-level header for node utility functions
+ */
+const require_story_name_extraction_1 = require("./require-story-name-extraction");
+/**
+ * Determine whether a node represents an anonymous arrow function expression
+ * where the parent variable declarator has no explicit Identifier name.
+ *
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-ARROW-FUNCTION-EXCLUDED
+ */
+function isAnonymousArrowFunction(node) {
+    return !!node && node.type === "ArrowFunctionExpression";
+}
+/**
+ * Determine whether a function-like node is nested within another function.
+ *
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-NESTED-FUNCTION-INHERITANCE
+ */
+function isNestedFunction(node) {
+    let current = node?.parent;
+    while (current) {
+        if (current.type === "FunctionDeclaration" ||
+            current.type === "FunctionExpression" ||
+            current.type === "ArrowFunctionExpression" ||
+            current.type === "MethodDefinition" ||
+            current.type === "TSDeclareFunction" ||
+            current.type === "TSMethodSignature") {
+            return true;
+        }
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Determine whether a function-like node is effectively anonymous for the
+ * purposes of nested-function inheritance. Named functions must always carry
+ * their own annotations, while anonymous nested functions may inherit.
+ *
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-NESTED-FUNCTION-INHERITANCE
+ */
+function isEffectivelyAnonymousFunction(node) {
+    const name = (0, require_story_name_extraction_1.getContainerKeyOrIdName)(node) ?? (0, require_story_name_extraction_1.getDirectIdentifierName)(node);
+    if (typeof name === "string" && name.length > 0 && name !== "(anonymous)") {
+        return false;
+    }
+    return true;
+}
+/**
+ * Determine if a node is in an export declaration
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Check node ancestry to find export declarations
+ */
+function isExportedNode(node) {
+    let p = node.parent;
+    while (p) {
+        if (p.type === "ExportNamedDeclaration" ||
+            p.type === "ExportDefaultDeclaration") {
+            return true;
+        }
+        p = p.parent;
+    }
+    return false;
+}
+/**
+ * Determine AST node where annotation should be inserted
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Determine correct insertion target for annotation
+ */
+function resolveTargetNode(sourceCode, node) {
+    if (node.type === "TSMethodSignature") {
+        // Interface method signature -> insert on interface
+        return node.parent.parent;
+    }
+    if (node.type === "FunctionExpression" ||
+        node.type === "ArrowFunctionExpression") {
+        const parent = node.parent;
+        if (parent.type === "VariableDeclarator") {
+            const varDecl = parent.parent;
+            if (varDecl.parent && varDecl.parent.type === "ExportNamedDeclaration") {
+                return varDecl.parent;
+            }
+            return varDecl;
+        }
+        if (parent.type === "ExportNamedDeclaration") {
+            return parent;
+        }
+        if (parent.type === "ExpressionStatement") {
+            return parent;
+        }
+    }
+    return node;
+}
+/**
+ * Resolve the node that should receive the `@story` annotation,
+ * respecting an explicitly passed target when provided.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Centralize annotation target node resolution
+ */
+function resolveAnnotationTargetNode(sourceCode, node, passedTarget) {
+    return passedTarget ?? resolveTargetNode(sourceCode, node);
+}

package/lib/src/rules/helpers/valid-annotation-format-internal.js

@@ -29,12 +29,20 @@ function normalizeCommentLine(rawLine) {
     // This ensures annotations that appear outside code spans are still
     // detected at their original indices.
     const filtered = trimmed.replace(/`[^`]*`/g, (match) => " ".repeat(match.length));
-    const annotationMatch = filtered.match(/@story\b|@req\b|@supports\b/);
+    // Remove leading star first to normalize JSDoc format
+    const withoutLeadingStar = filtered.replace(/^\*\s?/, "");
+    // Check if the line starts with a non-traceability JSDoc tag (e.g., @param, @returns)
+    // If so, return the whole line as-is to avoid false positives where annotation
+    // keywords appear in the tag's description (e.g., "`@returns` ... `@story` annotations")
+    if (/^@(?!story\b|req\b|supports\b)/.test(withoutLeadingStar)) {
+        return withoutLeadingStar;
+    }
+    // Otherwise, check for traceability annotations and slice to them if found
+    const annotationMatch = withoutLeadingStar.match(/@story\b|@req\b|@supports\b/);
     if (!annotationMatch || annotationMatch.index === undefined) {
-        const withoutLeadingStar = filtered.replace(/^\*\s?/, "");
         return withoutLeadingStar;
     }
-    return filtered.slice(annotationMatch.index);
+    return withoutLeadingStar.slice(annotationMatch.index);
 }
 /**
  * Detect whether a normalized comment line starts with a non-traceability JSDoc tag.

package/lib/src/rules/helpers/valid-annotation-options.d.ts

@@ -1,13 +1,3 @@
-/**
- * Shared option handling for the valid-annotation-format rule.
- *
- * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
- * @req REQ-PATTERN-CONFIG - Support configuration of custom story path and requirement ID patterns
- * @req REQ-REGEX-VALIDATION - Validate that configured patterns are valid regular expressions
- * @req REQ-BACKWARD-COMPAT - Maintain current behavior when no custom patterns configured
- * @req REQ-EXAMPLE-MESSAGES - Support optional example strings in error messages
- * @req REQ-SCHEMA-VALIDATION - Use JSON Schema to validate configuration options
- */
 export interface AnnotationRuleOptions {
     story?: {
         /**

package/lib/src/rules/helpers/valid-annotation-options.js

@@ -5,6 +5,17 @@ exports.getResolvedDefaults = getResolvedDefaults;
 exports.getOptionErrors = getOptionErrors;
 exports.resolveOptions = resolveOptions;
 exports.getRuleSchema = getRuleSchema;
+/**
+ * Shared option handling for the valid-annotation-format rule.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Support configuration of custom story path and requirement ID patterns
+ * @req REQ-REGEX-VALIDATION - Validate that configured patterns are valid regular expressions
+ * @req REQ-BACKWARD-COMPAT - Maintain current behavior when no custom patterns configured
+ * @req REQ-EXAMPLE-MESSAGES - Support optional example strings in error messages
+ * @req REQ-SCHEMA-VALIDATION - Use JSON Schema to validate configuration options
+ */
+const pattern_validators_1 = require("./pattern-validators");
 /**
  * Get the default regular expression used to validate story paths.
  *
@@ -84,92 +95,6 @@ function getOptionErrors() {
  * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
  * @req REQ-PATTERN-CONFIG - Provide consistent regex validation diagnostics
  */
-function buildInvalidRegexError(field, pattern) {
-    return `Invalid regular expression for option "${field}": "${pattern}"`;
-}
-/**
- * Normalize raw rule options into a single AnnotationRuleOptions object.
- *
- * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
- * @req REQ-PATTERN-CONFIG
- * @req REQ-BACKWARD-COMPAT
- */
-function normalizeUserOptions(rawOptions) {
-    if (!rawOptions || rawOptions.length === 0) {
-        return undefined;
-    }
-    const first = rawOptions[0];
-    if (!first || typeof first !== "object") {
-        return undefined;
-    }
-    return first;
-}
-/**
- * Resolve a user-configured regex pattern, handling both nested and flat
- * configuration shapes and accumulating validation errors.
- *
- * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
- * @req REQ-PATTERN-CONFIG
- * @req REQ-REGEX-VALIDATION
- * @req REQ-BACKWARD-COMPAT
- */
-function resolvePattern({ nestedPattern, nestedFieldName, flatPattern, flatFieldName, defaultPattern, }) {
-    const effective = typeof nestedPattern === "string"
-        ? { value: nestedPattern, field: nestedFieldName }
-        : typeof flatPattern === "string"
-            ? { value: flatPattern, field: flatFieldName }
-            : null;
-    if (!effective) {
-        return defaultPattern;
-    }
-    try {
-        return new RegExp(effective.value);
-    }
-    catch {
-        optionErrors.push(buildInvalidRegexError(effective.field, effective.value));
-        return defaultPattern;
-    }
-}
-/**
- * Resolve an example string, preferring nested over flat configuration,
- * and falling back to the provided default when necessary.
- *
- * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
- * @req REQ-EXAMPLE-MESSAGES
- * @req REQ-BACKWARD-COMPAT
- */
-function resolveExample(nestedExample, flatExample, defaultExample) {
-    if (typeof nestedExample === "string" && nestedExample.trim()) {
-        return nestedExample;
-    }
-    if (typeof flatExample === "string" && flatExample.trim()) {
-        return flatExample;
-    }
-    return defaultExample;
-}
-/**
- * Extract and normalize user-provided options from the raw ESLint
- * options array into an AnnotationRuleOptions object.
- *
- * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
- * @req REQ-PATTERN-CONFIG - Accept structured configuration for patterns
- * @req REQ-BACKWARD-COMPAT - Tolerate missing or malformed options
- */
-function getUserOptions(rawOptions) {
-    return normalizeUserOptions(rawOptions);
-}
-/**
- * Resolve the auto-fix flag, defaulting to true when the option
- * is not explicitly provided by the user.
- *
- * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
- * @req REQ-PATTERN-CONFIG - Support configuration of fix behavior
- * @req REQ-BACKWARD-COMPAT - Preserve default auto-fix behavior
- */
-function resolveAutoFixFlag(user) {
-    const autoFixFlag = user?.autoFix;
-    return typeof autoFixFlag === "boolean" ? autoFixFlag : true;
-}
 /**
  * Resolve the story path pattern from nested or flat configuration
  * fields, validating and falling back to the default as needed.
@@ -180,12 +105,13 @@ function resolveAutoFixFlag(user) {
  * @req REQ-BACKWARD-COMPAT - Use a default when no pattern is provided
  */
 function resolveStoryPattern(nestedStoryPattern, flatStoryPattern) {
-    return resolvePattern({
+    return (0, pattern_validators_1.resolvePattern)({
         nestedPattern: nestedStoryPattern,
         nestedFieldName: "story.pattern",
         flatPattern: flatStoryPattern,
         flatFieldName: "storyPathPattern",
         defaultPattern: getDefaultStoryPattern(),
+        errors: optionErrors,
     });
 }
 /**
@@ -198,12 +124,13 @@ function resolveStoryPattern(nestedStoryPattern, flatStoryPattern) {
  * @req REQ-BACKWARD-COMPAT - Use a default when no pattern is provided
  */
 function resolveReqPattern(nestedReqPattern, flatReqPattern) {
-    return resolvePattern({
+    return (0, pattern_validators_1.resolvePattern)({
         nestedPattern: nestedReqPattern,
         nestedFieldName: "req.pattern",
         flatPattern: flatReqPattern,
         flatFieldName: "requirementIdPattern",
         defaultPattern: getDefaultReqPattern(),
+        errors: optionErrors,
     });
 }
 /**
@@ -215,7 +142,7 @@ function resolveReqPattern(nestedReqPattern, flatReqPattern) {
  * @req REQ-BACKWARD-COMPAT - Use a default story example when omitted
  */
 function resolveStoryExample(nestedStoryExample, flatStoryExample) {
-    return resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
+    return (0, pattern_validators_1.resolveExample)(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
 }
 /**
  * Resolve the requirement ID example string from nested or flat configuration
@@ -226,7 +153,7 @@ function resolveStoryExample(nestedStoryExample, flatStoryExample) {
  * @req REQ-BACKWARD-COMPAT - Use a default requirement ID example when omitted
  */
 function resolveReqExample(nestedReqExample, flatReqExample) {
-    return resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
+    return (0, pattern_validators_1.resolveExample)(nestedReqExample, flatReqExample, getDefaultReqExample());
 }
 /**
  * Collect user-provided story pattern inputs from both nested and flat
@@ -298,7 +225,8 @@ function resolveOptionsInternal(user) {
     const { nestedStoryExample, flatStoryExample } = getStoryExampleInputs(user);
     const { nestedReqPattern, flatReqPattern } = getReqPatternInputs(user);
     const { nestedReqExample, flatReqExample } = getReqExampleInputs(user);
-    const autoFix = resolveAutoFixFlag(user);
+    const autoFixFlag = user?.autoFix;
+    const autoFix = typeof autoFixFlag === "boolean" ? autoFixFlag : true;
     const storyPattern = resolveStoryPattern(nestedStoryPattern, flatStoryPattern);
     const reqPattern = resolveReqPattern(nestedReqPattern, flatReqPattern);
     const storyExample = resolveStoryExample(nestedStoryExample, flatStoryExample);
@@ -322,7 +250,9 @@ function resolveOptionsInternal(user) {
  */
 function resolveOptions(rawOptions) {
     optionErrors = [];
-    const user = getUserOptions(rawOptions);
+    const user = rawOptions && rawOptions.length > 0 && typeof rawOptions[0] === "object"
+        ? rawOptions[0]
+        : undefined;
     const resolved = resolveOptionsInternal(user);
     resolvedDefaults = resolved;
     return resolvedDefaults;

package/lib/src/rules/helpers/valid-req-reference-helpers.js

@@ -5,7 +5,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createValidReqReferenceProgramVisitor = createValidReqReferenceProgramVisitor;
 /* eslint-disable traceability/valid-annotation-format */
-/* eslint-env node */
 /**
  * Helper utilities for the "valid-req-reference" rule.
  *

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

@@ -1,7 +1,6 @@
 "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");
+const redundancy_detector_1 = require("../utils/redundancy-detector");
 /**
  * ESLint rule to detect redundant traceability annotations on statements
  * that are already covered by their containing scope.
@@ -47,239 +46,6 @@ function normalizeOptions(raw) {
         alwaysCovered,
     };
 }
-/**
- * Collect comments around a scope node using JSDoc, leading comments,
- * and any comments that appear immediately before the node.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE
- */
-function getScopeCommentsFromJSDocAndLeading(sourceCode, scopeNode) {
-    const comments = [];
-    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 comments;
-}
-/**
- * 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. For non-branch scopes, we reuse a
- * shared helper that collects JSDoc, leading, and immediately-before
- * comments around the scope node.
- *
- * @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)) {
-        /**
-         * Inside-brace annotations used as branch-level indicators (inside placement
-         * mode) should not be folded into scopePairs for redundancy purposes; only
-         * before-brace annotations define the covering scope here.
-         *
-         * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-NON-REDUNDANT-INSIDE REQ-PLACEMENT-CONFIG
-         */
-        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent, "before");
-        return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
-    }
-    const comments = getScopeCommentsFromJSDocAndLeading(sourceCode, scopeNode);
-    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));
-}
-/**
- * Walk up enclosing scopes starting from the given scope node and
- * accumulate all story/requirement pairs, limited by maxScopeDepth.
- *
- * This keeps REQ-SCOPE-INHERITANCE and REQ-CONFIGURABLE-STRICTNESS
- * aligned with the story's configuration model while delegating the
- * actual comment parsing to getScopePairs.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE REQ-CONFIGURABLE-STRICTNESS
- */
-function collectScopePairs(context, startingScopeNode, maxScopeDepth) {
-    const result = new Set();
-    if (!startingScopeNode || maxScopeDepth <= 0) {
-        return result;
-    }
-    let current = startingScopeNode;
-    let depth = 0;
-    while (current && depth < maxScopeDepth) {
-        const parent = current.parent;
-        const pairs = getScopePairs(context, current, parent);
-        for (const key of pairs) {
-            result.add(key);
-        }
-        current = parent;
-        depth += 1;
-    }
-    return result;
-}
-/**
- * Extract statement-level comments and story/requirement pairs that are
- * relevant for redundancy analysis within a given scope.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-STATEMENT-SIGNIFICANCE REQ-SCOPE-ANALYSIS
- */
-function getStatementPairsForRedundancy(context, stmt, scopePairs, options) {
-    if (scopePairs.size === 0) {
-        return null;
-    }
-    if (!(0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES)) {
-        return null;
-    }
-    const stmtComments = getStatementComments(context, stmt);
-    if (stmtComments.length === 0) {
-        return null;
-    }
-    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) {
-        return null;
-    }
-    return { comments: stmtComments, pairs: stmtPairs };
-}
-/**
- * Decide whether the provided statement-level pairs should be considered
- * redundant within the given scope, respecting configuration options.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-CONFIGURABLE-STRICTNESS
- */
-function isStatementRedundantWithinScope(stmtPairs, scopePairs, options) {
-    if (options.allowEmphasisDuplication &&
-        stmtPairs.size === 1 &&
-        (0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
-        return false;
-    }
-    if (!(0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
-        return false;
-    }
-    return true;
-}
-/**
- * Filter a list of comments down to those that contain traceability
- * annotations relevant for redundancy detection.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL REQ-REDUNDANCY-PATTERNS
- */
-function getAnnotationCommentsFromStatement(comments) {
-    return comments.filter((comment) => {
-        const commentText = typeof comment.value === "string" ? comment.value : "";
-        return /@story\b|@req\b|@supports\b/.test(commentText);
-    });
-}
-/**
- * Determine whether a statement is redundant relative to the provided
- * scopePairs and options, using helper functions to gather statement
- * pairs, apply redundancy rules, and collect the associated annotation
- * comments. Returns null when the statement should not be treated as
- * redundant.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS
- */
-function getRedundantStatementContext(context, stmt, scopePairs, options) {
-    const stmtInfo = getStatementPairsForRedundancy(context, stmt, scopePairs, options);
-    if (!stmtInfo) {
-        return null;
-    }
-    const { comments, pairs } = stmtInfo;
-    if (!isStatementRedundantWithinScope(pairs, scopePairs, options)) {
-        return null;
-    }
-    const annotationComments = getAnnotationCommentsFromStatement(comments);
-    if (annotationComments.length === 0) {
-        return null;
-    }
-    return { comments: annotationComments };
-}
-/**
- * Compute unique removal ranges for the given annotation comments.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL
- */
-function getRemovalRangesForAnnotationComments(comments, sourceCode) {
-    const rangeMap = new Map();
-    for (const comment of comments) {
-        const [removalStart, removalEnd] = (0, annotation_scope_analyzer_1.getCommentRemovalRange)(comment, sourceCode);
-        const key = `${removalStart}:${removalEnd}`;
-        if (!rangeMap.has(key)) {
-            rangeMap.set(key, [removalStart, removalEnd]);
-        }
-    }
-    return Array.from(rangeMap.values()).sort((a, b) => b[0] - a[0]);
-}
-/**
- * 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 || scopePairs.size === 0)
-        return;
-    const sourceCode = context.getSourceCode();
-    for (const stmt of statements) {
-        const info = getRedundantStatementContext(context, stmt, scopePairs, options);
-        if (!info) {
-            continue;
-        }
-        const ranges = getRemovalRangesForAnnotationComments(info.comments, sourceCode);
-        if (ranges.length === 0) {
-            continue;
-        }
-        context.report({
-            node: stmt,
-            messageId: "redundantAnnotation",
-            fix(fixer) {
-                return ranges.map(([start, end]) => fixer.removeRange([start, end]));
-            },
-        });
-    }
-}
 const rule = {
     meta: {
         type: "suggestion",
@@ -337,11 +103,11 @@ const rule = {
                 if (parent && parent.type === "CatchClause") {
                     return;
                 }
-                const scopePairs = collectScopePairs(context, parent, options.maxScopeDepth);
-                debugScopePairs(parent, scopePairs);
+                const scopePairs = (0, redundancy_detector_1.collectScopePairs)(context, parent, options.maxScopeDepth);
+                (0, redundancy_detector_1.debugScopePairs)(parent, scopePairs);
                 if (scopePairs.size === 0)
                     return;
-                reportRedundantAnnotationsInBlock(context, node, scopePairs, options);
+                (0, redundancy_detector_1.reportRedundantAnnotationsInBlock)(context, node, scopePairs, options);
             },
         };
     },

package/lib/src/rules/prefer-implements-annotation.d.ts

@@ -23,6 +23,18 @@
  * @req REQ-AUTO-FIX - Provide safe, opt-in auto-fix for simple legacy patterns
  */
 import type { Rule } from "eslint";
+/**
+ * ESLint rule: prefer-implements-annotation
+ *
+ * Recommend migrating from legacy `@story` + `@req` annotations to the
+ * newer `@supports` format. This rule is **disabled by default** and
+ * is intended as an optional, opt-in migration aid.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
+ */
 /**
  * ESLint rule: prefer-implements-annotation
  *