eslint-plugin-traceability 1.11.0 → 1.11.2

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

@@ -1,14 +1,7 @@
 /**
  * Internal helpers and types for the valid-annotation-format rule.
  *
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
- * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- * @req REQ-SUPPORTS-PARSE - Parse @supports annotations without affecting @story/@req
- * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ * @supports docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md REQ-IGNORE-INLINE-CODE REQ-PRESERVE-BOUNDARIES REQ-CENTRALIZED-FILTER
  */
 /**
  * Pending annotation state tracked while iterating through comment lines.
@@ -21,8 +14,10 @@ export interface PendingAnnotation {
 /**
  * Normalize a raw comment line to make annotation parsing more robust.
  *
- * This function trims whitespace, keeps any annotation tags that appear
- * later in the line, and supports common JSDoc styles such as leading "*".
+ * This function trims whitespace, strips any inline code spans wrapped in
+ * backticks (replacing them with spaces of equal length to preserve character
+ * boundaries), keeps any annotation tags that appear later in the line, and
+ * supports common JSDoc styles such as leading "*".
  *
  * It detects @story, @req, and @supports tags while preserving the rest
  * of the line for downstream logic.
@@ -34,8 +29,12 @@ export declare function normalizeCommentLine(rawLine: string): string;
  * This is used to distinguish regular JSDoc tags (e.g. @param, @returns) from
  * traceability-related annotations such as @story, @req, and @supports.
  *
- * @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
- * @req REQ-JSDOC-BOUNDARY-DETECTION
- * @req REQ-JSDOC-TAG-COEXISTENCE
+ * Supports coexistence with JSDoc by:
+ * - Detecting boundaries between traceability tags and other tags
+ * - Allowing regular JSDoc tags to live alongside traceability annotations
+ *
+ * Related requirements:
+ * - REQ-JSDOC-BOUNDARY-DETECTION
+ * - REQ-JSDOC-TAG-COEXISTENCE
  */
 export declare function isNonTraceabilityJSDocTagLine(normalized: string): boolean;

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

@@ -2,14 +2,7 @@
 /**
  * Internal helpers and types for the valid-annotation-format rule.
  *
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
- * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- * @req REQ-SUPPORTS-PARSE - Parse @supports annotations without affecting @story/@req
- * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ * @supports docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md REQ-IGNORE-INLINE-CODE REQ-PRESERVE-BOUNDARIES REQ-CENTRALIZED-FILTER
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeCommentLine = normalizeCommentLine;
@@ -17,8 +10,10 @@ exports.isNonTraceabilityJSDocTagLine = isNonTraceabilityJSDocTagLine;
 /**
  * Normalize a raw comment line to make annotation parsing more robust.
  *
- * This function trims whitespace, keeps any annotation tags that appear
- * later in the line, and supports common JSDoc styles such as leading "*".
+ * This function trims whitespace, strips any inline code spans wrapped in
+ * backticks (replacing them with spaces of equal length to preserve character
+ * boundaries), keeps any annotation tags that appear later in the line, and
+ * supports common JSDoc styles such as leading "*".
  *
  * It detects @story, @req, and @supports tags while preserving the rest
  * of the line for downstream logic.
@@ -28,12 +23,18 @@ function normalizeCommentLine(rawLine) {
     if (!trimmed) {
         return "";
     }
-    const annotationMatch = trimmed.match(/@story\b|@req\b|@supports\b/);
+    // @supports docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md REQ-IGNORE-INLINE-CODE REQ-PRESERVE-BOUNDARIES REQ-CENTRALIZED-FILTER
+    // Strip backtick-wrapped content while preserving character positions by
+    // replacing each matched segment with spaces of the same length.
+    // 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/);
     if (!annotationMatch || annotationMatch.index === undefined) {
-        const withoutLeadingStar = trimmed.replace(/^\*\s?/, "");
+        const withoutLeadingStar = filtered.replace(/^\*\s?/, "");
         return withoutLeadingStar;
     }
-    return trimmed.slice(annotationMatch.index);
+    return filtered.slice(annotationMatch.index);
 }
 /**
  * Detect whether a normalized comment line starts with a non-traceability JSDoc tag.
@@ -41,9 +42,13 @@ function normalizeCommentLine(rawLine) {
  * This is used to distinguish regular JSDoc tags (e.g. @param, @returns) from
  * traceability-related annotations such as @story, @req, and @supports.
  *
- * @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
- * @req REQ-JSDOC-BOUNDARY-DETECTION
- * @req REQ-JSDOC-TAG-COEXISTENCE
+ * Supports coexistence with JSDoc by:
+ * - Detecting boundaries between traceability tags and other tags
+ * - Allowing regular JSDoc tags to live alongside traceability annotations
+ *
+ * Related requirements:
+ * - REQ-JSDOC-BOUNDARY-DETECTION
+ * - REQ-JSDOC-TAG-COEXISTENCE
  */
 function isNonTraceabilityJSDocTagLine(normalized) {
     const trimmed = normalized.trimStart();

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

@@ -2,9 +2,15 @@
  * Validators and helper functions for the valid-annotation-format rule.
  *
  * This module contains the core validation logic that was originally
- * embedded in src/rules/valid-annotation-format.ts. It is extracted
- * here to keep the main rule module smaller and easier to read while
- * preserving existing behavior.
+ * embedded in src/rules/valid-annotation-format.ts. The logic is extracted
+ * into this helper to keep the main rule implementation smaller and easier
+ * to read while still preserving all existing behavior.
+ *
+ * The implementation in this module supports:
+ * - validation of @story annotations
+ * - validation of @req annotations
+ * - validation of @implements/@supports-style annotations
+ * - safe, minimal auto-fixes for certain invalid formats
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
@@ -29,6 +35,8 @@ import type { PendingAnnotation } from "./valid-annotation-format-internal";
 /**
  * Report an invalid @story annotation without applying a fix.
  *
+ * The invalid @story annotation is detected and reported but left unchanged.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -55,6 +63,9 @@ export declare function createStoryFix(context: any, comment: any, fixed: string
  * for common path suffix issues by locating and replacing the path text
  * within the original comment.
  *
+ * Reporting includes both the original invalid value and, where applicable,
+ * a suggested corrected story path that only adjusts the suffix.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -68,6 +79,12 @@ export declare function reportInvalidStoryFormatWithFix(context: any, comment: a
  * Validate a @story annotation value and report detailed errors when needed.
  * Where safe and unambiguous, apply an automatic fix for missing suffixes.
  *
+ * Processing of @story values includes:
+ *   - trimming whitespace,
+ *   - collapsing multi-line text,
+ *   - matching against the configured story regex,
+ *   - and attempting a conservative suffix-only correction when possible.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -82,6 +99,11 @@ export declare function validateStoryAnnotation(context: any, comment: any, rawV
 /**
  * Validate a @req annotation value and report detailed errors when needed.
  *
+ * This behavior covers:
+ *   - detecting missing identifiers,
+ *   - collapsing multi-line requirement identifiers,
+ *   - and validating the final identifier against the configured regex.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -115,6 +137,10 @@ export declare function validateImplementsAnnotation(context: any, comment: any,
 /**
  * Finalize and validate the currently pending annotation, if any.
  *
+ * Pending annotation state is produced by earlier parsing of multi-line
+ * comments. This function dispatches that accumulated value to the
+ * appropriate validator and then clears the pending state.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md

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

@@ -3,9 +3,15 @@
  * Validators and helper functions for the valid-annotation-format rule.
  *
  * This module contains the core validation logic that was originally
- * embedded in src/rules/valid-annotation-format.ts. It is extracted
- * here to keep the main rule module smaller and easier to read while
- * preserving existing behavior.
+ * embedded in src/rules/valid-annotation-format.ts. The logic is extracted
+ * into this helper to keep the main rule implementation smaller and easier
+ * to read while still preserving all existing behavior.
+ *
+ * The implementation in this module supports:
+ * - validation of @story annotations
+ * - validation of @req annotations
+ * - validation of @implements/@supports-style annotations
+ * - safe, minimal auto-fixes for certain invalid formats
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
@@ -39,6 +45,8 @@ const valid_annotation_options_1 = require("./valid-annotation-options");
 /**
  * Report an invalid @story annotation without applying a fix.
  *
+ * The invalid @story annotation is detected and reported but left unchanged.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -99,6 +107,9 @@ function createStoryFix(context, comment, fixed) {
  * for common path suffix issues by locating and replacing the path text
  * within the original comment.
  *
+ * Reporting includes both the original invalid value and, where applicable,
+ * a suggested corrected story path that only adjusts the suffix.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -128,6 +139,12 @@ function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
  * Validate a @story annotation value and report detailed errors when needed.
  * Where safe and unambiguous, apply an automatic fix for missing suffixes.
  *
+ * Processing of @story values includes:
+ *   - trimming whitespace,
+ *   - collapsing multi-line text,
+ *   - matching against the configured story regex,
+ *   - and attempting a conservative suffix-only correction when possible.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -179,6 +196,11 @@ function validateStoryAnnotation(context, comment, rawValue, options) {
 /**
  * Validate a @req annotation value and report detailed errors when needed.
  *
+ * This behavior covers:
+ *   - detecting missing identifiers,
+ *   - collapsing multi-line requirement identifiers,
+ *   - and validating the final identifier against the configured regex.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -247,6 +269,10 @@ function validateImplementsAnnotation(context, comment, rawValue, options) {
 /**
  * Finalize and validate the currently pending annotation, if any.
  *
+ * Pending annotation state is produced by earlier parsing of multi-line
+ * comments. This function dispatches that accumulated value to the
+ * appropriate validator and then clears the pending state.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md

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

@@ -119,6 +119,9 @@ export declare function getRuleSchema(): {
         requirementIdExample: {
             type: string;
         };
+        autoFix: {
+            type: string;
+        };
     };
     additionalProperties: boolean;
 }[];

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

@@ -105,46 +105,88 @@ function resolveExample(nestedExample, flatExample, defaultExample) {
     }
     return defaultExample;
 }
-/**
- * Resolve user options into concrete, validated configuration.
- * Falls back to existing defaults when options are not provided or invalid.
- */
-function resolveOptions(rawOptions) {
-    optionErrors = [];
-    const user = normalizeUserOptions(rawOptions);
-    const nestedStoryPattern = user?.story?.pattern;
-    const flatStoryPattern = user?.storyPathPattern;
-    const nestedStoryExample = user?.story?.example;
-    const flatStoryExample = user?.storyPathExample;
-    const nestedReqPattern = user?.req?.pattern;
-    const flatReqPattern = user?.requirementIdPattern;
-    const nestedReqExample = user?.req?.example;
-    const flatReqExample = user?.requirementIdExample;
+function getUserOptions(rawOptions) {
+    return normalizeUserOptions(rawOptions);
+}
+function resolveAutoFixFlag(user) {
     const autoFixFlag = user?.autoFix;
-    const autoFix = typeof autoFixFlag === "boolean" ? autoFixFlag : true;
-    const storyPattern = resolvePattern({
+    return typeof autoFixFlag === "boolean" ? autoFixFlag : true;
+}
+function resolveStoryPattern(nestedStoryPattern, flatStoryPattern) {
+    return resolvePattern({
         nestedPattern: nestedStoryPattern,
         nestedFieldName: "story.pattern",
         flatPattern: flatStoryPattern,
         flatFieldName: "storyPathPattern",
         defaultPattern: getDefaultStoryPattern(),
     });
-    const reqPattern = resolvePattern({
+}
+function resolveReqPattern(nestedReqPattern, flatReqPattern) {
+    return resolvePattern({
         nestedPattern: nestedReqPattern,
         nestedFieldName: "req.pattern",
         flatPattern: flatReqPattern,
         flatFieldName: "requirementIdPattern",
         defaultPattern: getDefaultReqPattern(),
     });
-    const storyExample = resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
-    const reqExample = resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
-    resolvedDefaults = {
+}
+function resolveStoryExample(nestedStoryExample, flatStoryExample) {
+    return resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
+}
+function resolveReqExample(nestedReqExample, flatReqExample) {
+    return resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
+}
+function getStoryPatternInputs(user) {
+    return {
+        nestedStoryPattern: user?.story?.pattern,
+        flatStoryPattern: user?.storyPathPattern,
+    };
+}
+function getStoryExampleInputs(user) {
+    return {
+        nestedStoryExample: user?.story?.example,
+        flatStoryExample: user?.storyPathExample,
+    };
+}
+function getReqPatternInputs(user) {
+    return {
+        nestedReqPattern: user?.req?.pattern,
+        flatReqPattern: user?.requirementIdPattern,
+    };
+}
+function getReqExampleInputs(user) {
+    return {
+        nestedReqExample: user?.req?.example,
+        flatReqExample: user?.requirementIdExample,
+    };
+}
+function resolveOptionsInternal(user) {
+    const { nestedStoryPattern, flatStoryPattern } = getStoryPatternInputs(user);
+    const { nestedStoryExample, flatStoryExample } = getStoryExampleInputs(user);
+    const { nestedReqPattern, flatReqPattern } = getReqPatternInputs(user);
+    const { nestedReqExample, flatReqExample } = getReqExampleInputs(user);
+    const autoFix = resolveAutoFixFlag(user);
+    const storyPattern = resolveStoryPattern(nestedStoryPattern, flatStoryPattern);
+    const reqPattern = resolveReqPattern(nestedReqPattern, flatReqPattern);
+    const storyExample = resolveStoryExample(nestedStoryExample, flatStoryExample);
+    const reqExample = resolveReqExample(nestedReqExample, flatReqExample);
+    return {
         storyPattern,
         storyExample,
         reqPattern,
         reqExample,
         autoFix,
     };
+}
+/**
+ * Resolve user options into concrete, validated configuration.
+ * Falls back to existing defaults when options are not provided or invalid.
+ */
+function resolveOptions(rawOptions) {
+    optionErrors = [];
+    const user = getUserOptions(rawOptions);
+    const resolved = resolveOptionsInternal(user);
+    resolvedDefaults = resolved;
     return resolvedDefaults;
 }
 /**
@@ -175,6 +217,7 @@ function getRuleSchema() {
                 storyPathExample: { type: "string" },
                 requirementIdPattern: { type: "string" },
                 requirementIdExample: { type: "string" },
+                autoFix: { type: "boolean" },
             },
             additionalProperties: false,
         },

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

@@ -44,7 +44,7 @@ export declare function collapseAnnotationValue(value: string): string;
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
  * @story docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
@@ -56,7 +56,7 @@ export declare function getFixedStoryPath(original: string): string | null;
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
@@ -66,7 +66,7 @@ export declare function buildStoryErrorMessage(kind: "missing" | "invalid", valu
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */

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

@@ -54,19 +54,19 @@ function collapseAnnotationValue(value) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
  * @story docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
  * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
  */
 function getFixedStoryPath(original) {
-    // @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md | REQ-AUTOFIX-SAFE - Reject auto-fix when the path contains ".." traversal segments to avoid broadening the reference.
+    // @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md | REQ-AUTOFIX-SAFE - Reject auto-fix when the path contains ".." traversal segments to avoid broadening the reference.
     // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by rejecting paths that use unsafe traversal segments.
     if (original.includes("..")) {
         // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
         // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-SAFE
-        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-SAFE
+        // @supports docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md REQ-AUTOFIX-SAFE
         return null;
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md | REQ-AUTOFIX-FORMAT - Leave correctly formatted ".story.md" paths unchanged so diagnostics are not hidden by redundant fixes.
@@ -74,7 +74,7 @@ function getFixedStoryPath(original) {
     if (/\.story\.md$/.test(original)) {
         // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
         // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT
-        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-FORMAT
+        // @supports docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md REQ-AUTOFIX-FORMAT
         return null;
     }
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE - When ".story" is present but ".md" is missing, append only the extension without altering the base path.
@@ -105,7 +105,7 @@ function getFixedStoryPath(original) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
@@ -115,11 +115,11 @@ function buildStoryErrorMessage(kind, value, options) {
     // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the story identifier by emitting a targeted message when the @story value is absent.
     if (kind === "missing") {
         // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md REQ-ERROR-SPECIFICITY
         return `Missing story path for @story annotation. Expected a path like "${example}".`;
     }
     // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-    // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md REQ-ERROR-SPECIFICITY
     return `Invalid story path "${value ?? ""}" for @story annotation. Expected a path like "${example}".`;
 }
 /**
@@ -127,7 +127,7 @@ function buildStoryErrorMessage(kind, value, options) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
@@ -137,10 +137,10 @@ function buildReqErrorMessage(kind, value, options) {
     // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the requirement identifier by emitting a specific message when the @req value is missing.
     if (kind === "missing") {
         // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md REQ-ERROR-SPECIFICITY
         return `Missing requirement ID for @req annotation. Expected an identifier like "${example}".`;
     }
     // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-    // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md REQ-ERROR-SPECIFICITY
     return `Invalid requirement ID "${value ?? ""}" for @req annotation. Expected an identifier like "${example}" (uppercase letters, numbers, and dashes only).`;
 }

package/lib/src/rules/helpers/valid-req-reference-helpers.d.ts

@@ -0,0 +1,11 @@
+import type { Rule } from "eslint";
+/**
+ * Factory used by the valid-req-reference rule to construct its Program
+ * visitor. Keeping this in a helper module allows the rule entrypoint
+ * itself to remain small and focused on meta configuration while the
+ * heavier deep-validation logic is encapsulated here.
+ *
+ * @supports docs/stories/010.0-DEV-DEEP-VALIDATION.story.md REQ-DEEP-PARSE REQ-DEEP-MATCH REQ-DEEP-CACHE
+ * @supports docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-SUPPORTS-VALIDATE REQ-MIXED-SUPPORT REQ-SCOPED-IDS
+ */
+export declare function createValidReqReferenceProgramVisitor(context: Rule.RuleContext): () => void;