eslint-plugin-traceability 1.13.1 → 1.14.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.13.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.13.0...v1.13.1) (2025-12-08)
+## [1.14.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.14.0...v1.14.1) (2025-12-08)
 
 
 ### Bug Fixes
 
-* refine no-redundant-annotation rule tests and behavior ([7d72670](https://github.com/voder-ai/eslint-plugin-traceability/commit/7d726702e3ad2268778c06de3f3a9673033e3a61))
+* implement branch and function behaviors for branch annotations story ([00f9655](https://github.com/voder-ai/eslint-plugin-traceability/commit/00f9655c8a284278d69c7d09d106a340ada57827))
 
 # Changelog
 

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

@@ -82,6 +82,7 @@ function createMethodFix(node, annotationTemplate) {
 exports.DEFAULT_SCOPE = [
     "FunctionDeclaration",
     "FunctionExpression",
+    "ArrowFunctionExpression",
     "MethodDefinition",
     "TSMethodSignature",
     "TSDeclareFunction",

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

@@ -18,6 +18,7 @@ interface ReportOptions {
     annotationTemplateOverride?: string;
     autoFixToggle?: boolean;
 }
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 declare function getAnnotationTemplate(override?: string): string;
 declare function shouldApplyAutoFix(autoFix: boolean | undefined): boolean;
 /**
@@ -63,12 +64,15 @@ declare function resolveTargetNode(sourceCode: any, node: any): any;
  * @req REQ-ANNOTATION-REQUIRED - Walk node and parents to find Identifier/Key name
  */
 declare function extractName(node: any): string;
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 declare function shouldProcessNode(node: any, scope: string[], exportPriority?: string): boolean;
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 declare function reportMissing(context: Rule.RuleContext, sourceCode: any, config: {
     node: any;
     target?: any;
     options?: ReportOptions;
 }): void;
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 declare function reportMethod(context: Rule.RuleContext, sourceCode: any, config: {
     node: any;
     target?: any;

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

@@ -23,6 +23,7 @@ const require_story_core_1 = require("./require-story-core");
 Object.defineProperty(exports, "DEFAULT_SCOPE", { enumerable: true, get: function () { return require_story_core_1.DEFAULT_SCOPE; } });
 Object.defineProperty(exports, "EXPORT_PRIORITY_VALUES", { enumerable: true, get: function () { return require_story_core_1.EXPORT_PRIORITY_VALUES; } });
 Object.defineProperty(exports, "STORY_PATH", { enumerable: true, get: function () { return require_story_core_1.STORY_PATH; } });
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function getAnnotationTemplate(override) {
     if (typeof override === "string" && override.trim().length > 0) {
         return override.trim();
@@ -39,11 +40,81 @@ function shouldApplyAutoFix(autoFix) {
  * Build the effective annotation template and autofix toggle
  * from the provided report options.
  */
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function buildTemplateConfig(options) {
     const effectiveTemplate = getAnnotationTemplate(options?.annotationTemplateOverride);
     const allowFix = shouldApplyAutoFix(options?.autoFixToggle);
     return { effectiveTemplate, allowFix };
 }
+/**
+ * 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 = getContainerKeyOrIdName(node) ?? getDirectIdentifierName(node);
+    if (typeof name === "string" && name.length > 0 && name !== "(anonymous)") {
+        return false;
+    }
+    return true;
+}
+/**
+ * Determine whether a function node is required to carry its own annotation
+ * according to Story 004.0-DEV-BRANCH-ANNOTATIONS rules.
+ *
+ * - Anonymous arrow functions used as callbacks are excluded from
+ *   function-level annotation requirements.
+ * - Named arrow functions must be annotated.
+ * - Nested anonymous functions may inherit their parent function's
+ *   annotation and therefore are not required to be annotated directly.
+ * - Named nested functions must always carry their own explicit annotations.
+ *
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-ARROW-FUNCTION-EXCLUDED REQ-NESTED-FUNCTION-INHERITANCE
+ */
+function requiresOwnFunctionAnnotation(node) {
+    // Anonymous arrow functions used as callbacks are excluded from function-level
+    // requirements when they are nested inside another function or method.
+    if (isAnonymousArrowFunction(node) &&
+        isNestedFunction(node) &&
+        isEffectivelyAnonymousFunction(node)) {
+        return false;
+    }
+    if (isNestedFunction(node) && isEffectivelyAnonymousFunction(node)) {
+        return false;
+    }
+    return true;
+}
 /**
  * Determine if a node is in an export declaration
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -105,6 +176,7 @@ function leadingCommentsHasStory(node) {
  */
 function hasStoryAnnotation(sourceCode, node) {
     try {
+        // Direct, node-local checks always apply first.
         if (jsdocHasStory(sourceCode, node)) {
             return true;
         }
@@ -114,13 +186,20 @@ function hasStoryAnnotation(sourceCode, node) {
         if (leadingCommentsHasStory(node)) {
             return true;
         }
-        if ((0, require_story_io_1.linesBeforeHasStory)(sourceCode, node)) {
+        if (!isNestedFunction(node) && (0, require_story_io_1.linesBeforeHasStory)(sourceCode, node)) {
+            return true;
+        }
+        const canInherit = isNestedFunction(node) && isEffectivelyAnonymousFunction(node);
+        // Only nodes that are allowed to inherit annotations (e.g., nested anonymous
+        // callbacks) may treat parent-chain comments or broad fallback text as
+        // satisfying the annotation requirement.
+        if (canInherit && (0, require_story_io_1.parentChainHasStory)(sourceCode, node)) {
             return true;
         }
-        if ((0, require_story_io_1.parentChainHasStory)(sourceCode, node)) {
+        if (canInherit && (0, require_story_io_1.fallbackTextBeforeHasStory)(sourceCode, node)) {
             return true;
         }
-        if ((0, require_story_io_1.fallbackTextBeforeHasStory)(sourceCode, node)) {
+        if (canInherit) {
             return true;
         }
     }
@@ -226,7 +305,15 @@ function extractName(node) {
     }
     return "(anonymous)";
 }
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function shouldProcessNode(node, scope, exportPriority = "all") {
+    if (node &&
+        (node.type === "FunctionDeclaration" ||
+            node.type === "FunctionExpression" ||
+            node.type === "ArrowFunctionExpression") &&
+        !requiresOwnFunctionAnnotation(node)) {
+        return false;
+    }
     if (!scope.includes(node.type)) {
         return false;
     }
@@ -271,6 +358,7 @@ function getNameNodeForReport(node) {
 function resolveAnnotationTargetNode(sourceCode, node, passedTarget) {
     return passedTarget ?? resolveTargetNode(sourceCode, node);
 }
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function reportMissing(context, sourceCode, config) {
     (0, require_story_core_1.coreReportMissing)({
         hasStoryAnnotation,
@@ -285,6 +373,7 @@ function reportMissing(context, sourceCode, config) {
         createMethodFix: require_story_core_1.createMethodFix,
     }, context, sourceCode, config);
 }
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function reportMethod(context, sourceCode, config) {
     (0, require_story_core_1.coreReportMethod)({
         hasStoryAnnotation,

package/lib/src/rules/helpers/require-test-traceability-helpers.js

@@ -94,6 +94,11 @@ function ensureFileSupportsAnnotation(context, sourceCode, autoFixOptions) {
 function isTestCallName(name) {
     return ["describe", "it", "test", "context"].includes(name);
 }
+/**
+ * Extract the test framework call name from a CallExpression callee.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FRAMEWORK-COMPAT
+ */
 function getCalleeName(node) {
     if (node.callee.type === "Identifier") {
         return node.callee.name;
@@ -104,6 +109,11 @@ function getCalleeName(node) {
     }
     return null;
 }
+/**
+ * Extract the first string literal argument from a CallExpression, if present.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX
+ */
 function getFirstArgumentLiteral(node) {
     const arg = node.arguments && node.arguments[0];
     if (!arg)
@@ -189,6 +199,13 @@ function createUpdatedStringLiteralRaw(originalNode, newValue, sourceCode) {
     // Fallback: let JSON.stringify choose a safe representation.
     return JSON.stringify(newValue);
 }
+/**
+ * Validate describe() calls to ensure they include a story reference
+ * matching the configured describeRegex when required.
+ *
+ * @story docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
+ * @req REQ-TEST-DESCRIBE-STORY
+ */
 function handleDescribeCall(context, node, description, options) {
     const { describeRegex, requireDescribeStory } = options;
     if (!requireDescribeStory)
@@ -200,6 +217,13 @@ function handleDescribeCall(context, node, description, options) {
         });
     }
 }
+/**
+ * Validate it() and test() calls to ensure their descriptions start with a
+ * [REQ-XXX] prefix, optionally normalizing malformed prefixes when enabled.
+ *
+ * @story docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
+ * @req REQ-TEST-IT-REQ-PREFIX
+ */
 function handleItOrTestCall(context, node, description, options) {
     const { sourceCode, requireTestReqPrefix, autoFixTestPrefixFormat } = options;
     if (!requireTestReqPrefix)

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

@@ -69,16 +69,47 @@ export interface ResolvedAnnotationOptions {
     reqExample: string;
     autoFix: boolean;
 }
+/**
+ * Get the default requirement ID example string used in error messages.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Provide a default requirement ID example value
+ */
 export declare function getDefaultReqExample(): string;
+/**
+ * Expose the most recently resolved options so other helpers can reuse
+ * the same defaults without re-resolving configuration.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Share resolved default patterns across helpers
+ * @req REQ-BACKWARD-COMPAT - Maintain a stable default configuration
+ */
 export declare function getResolvedDefaults(): ResolvedAnnotationOptions;
+/**
+ * Retrieve an array of configuration error messages collected during
+ * option resolution, typically regex validation failures.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Surface configuration problems to callers
+ */
 export declare function getOptionErrors(): string[];
 /**
  * Resolve user options into concrete, validated configuration.
  * Falls back to existing defaults when options are not provided or invalid.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Drive rule behavior from configurable patterns
+ * @req REQ-REGEX-VALIDATION - Validate all configured regex patterns
+ * @req REQ-BACKWARD-COMPAT - Maintain behavior when no custom options set
  */
 export declare function resolveOptions(rawOptions: unknown[]): ResolvedAnnotationOptions;
 /**
- * Build the JSON schema for rule options.
+ * Build the JSON Schema definition that validates rule configuration
+ * passed to ESLint, ensuring option shapes and types are correct.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-SCHEMA-VALIDATION - Define a JSON Schema for rule options
+ * @req REQ-PATTERN-CONFIG - Describe configurable pattern and example fields
  */
 export declare function getRuleSchema(): {
     type: string;

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

@@ -5,15 +5,39 @@ exports.getResolvedDefaults = getResolvedDefaults;
 exports.getOptionErrors = getOptionErrors;
 exports.resolveOptions = resolveOptions;
 exports.getRuleSchema = getRuleSchema;
+/**
+ * Get the default regular expression used to validate story paths.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Provide a default story path pattern
+ */
 function getDefaultStoryPattern() {
     return /^docs\/stories\/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$/;
 }
+/**
+ * Get the default story example string used in error messages.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Provide a default story example value
+ */
 function getDefaultStoryExample() {
     return "docs/stories/005.0-DEV-EXAMPLE.story.md";
 }
+/**
+ * Get the default regular expression used to validate requirement IDs.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Provide a default requirement ID pattern
+ */
 function getDefaultReqPattern() {
     return /^REQ-[A-Z0-9-]+$/;
 }
+/**
+ * Get the default requirement ID example string used in error messages.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Provide a default requirement ID example value
+ */
 function getDefaultReqExample() {
     return "REQ-EXAMPLE";
 }
@@ -32,15 +56,33 @@ let resolvedDefaults = {
  * Collected configuration errors encountered while resolving options.
  */
 let optionErrors = [];
+/**
+ * Expose the most recently resolved options so other helpers can reuse
+ * the same defaults without re-resolving configuration.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Share resolved default patterns across helpers
+ * @req REQ-BACKWARD-COMPAT - Maintain a stable default configuration
+ */
 function getResolvedDefaults() {
     return resolvedDefaults;
 }
+/**
+ * Retrieve an array of configuration error messages collected during
+ * option resolution, typically regex validation failures.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Surface configuration problems to callers
+ */
 function getOptionErrors() {
     return optionErrors;
 }
 /**
  * Build a stable, engine-independent configuration error message
  * for invalid regex options.
+ *
+ * @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}"`;
@@ -105,13 +147,38 @@ function resolveExample(nestedExample, flatExample, defaultExample) {
     }
     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.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Allow configurable story path patterns
+ * @req REQ-REGEX-VALIDATION - Validate story path regex options
+ * @req REQ-BACKWARD-COMPAT - Use a default when no pattern is provided
+ */
 function resolveStoryPattern(nestedStoryPattern, flatStoryPattern) {
     return resolvePattern({
         nestedPattern: nestedStoryPattern,
@@ -121,6 +188,15 @@ function resolveStoryPattern(nestedStoryPattern, flatStoryPattern) {
         defaultPattern: getDefaultStoryPattern(),
     });
 }
+/**
+ * Resolve the requirement ID pattern from nested or flat configuration
+ * fields, validating and falling back to the default as needed.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Allow configurable requirement ID patterns
+ * @req REQ-REGEX-VALIDATION - Validate requirement ID regex options
+ * @req REQ-BACKWARD-COMPAT - Use a default when no pattern is provided
+ */
 function resolveReqPattern(nestedReqPattern, flatReqPattern) {
     return resolvePattern({
         nestedPattern: nestedReqPattern,
@@ -130,36 +206,93 @@ function resolveReqPattern(nestedReqPattern, flatReqPattern) {
         defaultPattern: getDefaultReqPattern(),
     });
 }
+/**
+ * Resolve the story example string from nested or flat configuration
+ * fields, preferring user-provided values and falling back to the default.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-EXAMPLE-MESSAGES - Allow custom story examples in messages
+ * @req REQ-BACKWARD-COMPAT - Use a default story example when omitted
+ */
 function resolveStoryExample(nestedStoryExample, flatStoryExample) {
     return resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
 }
+/**
+ * Resolve the requirement ID example string from nested or flat configuration
+ * fields, preferring user-provided values and falling back to the default.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-EXAMPLE-MESSAGES - Allow custom requirement ID examples in messages
+ * @req REQ-BACKWARD-COMPAT - Use a default requirement ID example when omitted
+ */
 function resolveReqExample(nestedReqExample, flatReqExample) {
     return resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
 }
+/**
+ * Collect user-provided story pattern inputs from both nested and flat
+ * configuration fields to support backward-compatible shapes.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Read story patterns from multiple option shapes
+ * @req REQ-BACKWARD-COMPAT - Support legacy flat storyPathPattern
+ */
 function getStoryPatternInputs(user) {
     return {
         nestedStoryPattern: user?.story?.pattern,
         flatStoryPattern: user?.storyPathPattern,
     };
 }
+/**
+ * Collect user-provided story example inputs from both nested and flat
+ * configuration fields to support backward-compatible shapes.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-EXAMPLE-MESSAGES - Read story examples from multiple option shapes
+ * @req REQ-BACKWARD-COMPAT - Support legacy flat storyPathExample
+ */
 function getStoryExampleInputs(user) {
     return {
         nestedStoryExample: user?.story?.example,
         flatStoryExample: user?.storyPathExample,
     };
 }
+/**
+ * Collect user-provided requirement ID pattern inputs from both nested
+ * and flat configuration fields to support backward-compatible shapes.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Read requirement ID patterns from multiple shapes
+ * @req REQ-BACKWARD-COMPAT - Support legacy flat requirementIdPattern
+ */
 function getReqPatternInputs(user) {
     return {
         nestedReqPattern: user?.req?.pattern,
         flatReqPattern: user?.requirementIdPattern,
     };
 }
+/**
+ * Collect user-provided requirement ID example inputs from both nested
+ * and flat configuration fields to support backward-compatible shapes.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-EXAMPLE-MESSAGES - Read requirement ID examples from multiple shapes
+ * @req REQ-BACKWARD-COMPAT - Support legacy flat requirementIdExample
+ */
 function getReqExampleInputs(user) {
     return {
         nestedReqExample: user?.req?.example,
         flatReqExample: user?.requirementIdExample,
     };
 }
+/**
+ * Internal helper to resolve all rule options into a concrete, validated
+ * ResolvedAnnotationOptions structure, applying defaults and validation.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Combine pattern and example configuration
+ * @req REQ-REGEX-VALIDATION - Enforce regex validity during resolution
+ * @req REQ-BACKWARD-COMPAT - Respect defaults when options are missing
+ */
 function resolveOptionsInternal(user) {
     const { nestedStoryPattern, flatStoryPattern } = getStoryPatternInputs(user);
     const { nestedStoryExample, flatStoryExample } = getStoryExampleInputs(user);
@@ -181,6 +314,11 @@ function resolveOptionsInternal(user) {
 /**
  * Resolve user options into concrete, validated configuration.
  * Falls back to existing defaults when options are not provided or invalid.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Drive rule behavior from configurable patterns
+ * @req REQ-REGEX-VALIDATION - Validate all configured regex patterns
+ * @req REQ-BACKWARD-COMPAT - Maintain behavior when no custom options set
  */
 function resolveOptions(rawOptions) {
     optionErrors = [];
@@ -190,7 +328,12 @@ function resolveOptions(rawOptions) {
     return resolvedDefaults;
 }
 /**
- * Build the JSON schema for rule options.
+ * Build the JSON Schema definition that validates rule configuration
+ * passed to ESLint, ensuring option shapes and types are correct.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-SCHEMA-VALIDATION - Define a JSON Schema for rule options
+ * @req REQ-PATTERN-CONFIG - Describe configurable pattern and example fields
  */
 function getRuleSchema() {
     return [

package/lib/src/rules/helpers/valid-implements-utils.js

@@ -81,10 +81,14 @@ function reportInvalidImplementsReqId(context, comment, reqId, options) {
     });
 }
 /**
- * Prepare and validate the token array for an @supports value.
+ * Parse the raw token stream for an @implements annotation into a structured
+ * representation with a single storyPath and an array of requirement IDs.
  *
- * Returns { storyPath, reqIds } when tokens are present and structurally valid,
- * or null when a missing-value condition has been reported.
+ * Handles trimming, token splitting, and basic structural checks, and reports
+ * missing-value conditions via the provided dependency helpers.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-TOKENS
  */
 function parseImplementsTokens(deps, context, comment, rest) {
     const { MIN_IMPLEMENTS_TOKENS, reportMissingImplementsValue, reportMissingImplementsReqIds, } = deps;
@@ -103,8 +107,12 @@ function parseImplementsTokens(deps, context, comment, rest) {
     return { storyPath, reqIds };
 }
 /**
- * Validate the parsed storyPath and reqIds against the provided patterns and
- * delegate reporting of any invalid tokens.
+ * Validate a previously parsed @implements token structure against configured
+ * story and requirement patterns, reporting any configuration or format errors
+ * via the supplied dependency helpers.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-TOKENS
  */
 function validateImplementsTokens(deps, context, comment, rest) {
     const { reportInvalidImplementsStoryPath, reportInvalidImplementsReqId } = deps;

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

@@ -21,6 +21,12 @@ const DEFAULT_ALWAYS_COVERED_STATEMENTS = [
 const DEFAULT_STRICTNESS = "moderate";
 const DEFAULT_ALLOW_EMPHASIS_DUPLICATION = false;
 const DEFAULT_MAX_SCOPE_DEPTH = 3;
+/**
+ * Normalize and apply defaults to rule options for the redundancy detector.
+ *
+ * @story docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md
+ * @req REQ-REDUNDANT-OPTIONS
+ */
 function normalizeOptions(raw) {
     const strictness = raw && typeof raw.strictness === "string"
         ? raw.strictness
@@ -287,6 +293,12 @@ const rule = {
             redundantAnnotation: "Annotation on this statement is redundant; it is already covered by its containing scope.",
         },
     },
+    /**
+     * Wire up the ESLint visitors that detect and fix redundant annotations.
+     *
+     * @story docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md
+     * @req REQ-REDUNDANT-DETECTION
+     */
     create(context) {
         const options = normalizeOptions(context.options[0]);
         return {