eslint-plugin-traceability 1.11.1 → 1.11.2

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

@@ -23,38 +23,34 @@ 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; } });
-/**
- * Derive the annotation template, optionally using an override.
- * When override is a non-empty string, its trimmed value is used.
- * Otherwise, the default template is returned.
- */
 function getAnnotationTemplate(override) {
     if (typeof override === "string" && override.trim().length > 0) {
         return override.trim();
     }
     return `/** @story ${require_story_core_1.STORY_PATH} */`;
 }
-/**
- * Determine whether auto-fix should be applied.
- * Explicit false disables auto-fix; all other values enable it.
- */
 function shouldApplyAutoFix(autoFix) {
     if (autoFix === false) {
         return false;
     }
     return true;
 }
+/**
+ * Build the effective annotation template and autofix toggle
+ * from the provided report options.
+ */
+function buildTemplateConfig(options) {
+    const effectiveTemplate = getAnnotationTemplate(options?.annotationTemplateOverride);
+    const allowFix = shouldApplyAutoFix(options?.autoFixToggle);
+    return { effectiveTemplate, allowFix };
+}
 /**
  * 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
- * @param {any} node - AST node to check for export ancestry
- * @returns {boolean} true if node is within an export declaration
  */
 function isExportedNode(node) {
     let p = node.parent;
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQUIRED - Walk parent chain to find Export declarations
     while (p) {
         if (p.type === "ExportNamedDeclaration" ||
             p.type === "ExportDefaultDeclaration") {
@@ -68,9 +64,6 @@ function isExportedNode(node) {
  * Check whether the JSDoc associated with node contains @story
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Extract JSDoc based detection into helper
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - AST node to inspect
- * @returns {boolean} true if JSDoc contains @story
  */
 function jsdocHasStory(sourceCode, node) {
     if (typeof sourceCode?.getJSDocComment !== "function") {
@@ -85,9 +78,6 @@ function jsdocHasStory(sourceCode, node) {
  * Check whether comments returned by sourceCode.getCommentsBefore contain @story
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Extract comment-before detection into helper
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - AST node to inspect
- * @returns {boolean} true if any preceding comment contains @story
  */
 function commentsBeforeHasStory(sourceCode, node) {
     if (typeof sourceCode?.getCommentsBefore !== "function") {
@@ -101,8 +91,6 @@ function commentsBeforeHasStory(sourceCode, node) {
  * Check whether leadingComments attached to the node contain @story
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Extract leadingComments detection into helper
- * @param {any} node - AST node to inspect
- * @returns {boolean} true if any leading comment contains @story
  */
 function leadingCommentsHasStory(node) {
     const leadingComments = (node && node.leadingComments) || [];
@@ -114,9 +102,6 @@ function leadingCommentsHasStory(node) {
  * Consolidates a variety of heuristics through smaller helpers.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Detect existing story annotations in JSDoc or comments
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - AST node to inspect for existing annotations
- * @returns {boolean} true if @story annotation already present
  */
 function hasStoryAnnotation(sourceCode, node) {
     try {
@@ -139,8 +124,10 @@ function hasStoryAnnotation(sourceCode, node) {
             return true;
         }
     }
-    catch {
-        /* noop */
+    catch (error) {
+        if (process.env.TRACEABILITY_DEBUG === "1") {
+            console.error("[traceability] hasStoryAnnotation failed for node", error?.message ?? error);
+        }
     }
     return false;
 }
@@ -148,9 +135,6 @@ function hasStoryAnnotation(sourceCode, node) {
  * 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
- * @param {any} sourceCode - ESLint sourceCode object (unused but kept for parity)
- * @param {any} node - function-like AST node to resolve target for
- * @returns {any} AST node that should receive the annotation
  */
 function resolveTargetNode(sourceCode, node) {
     if (node.type === "TSMethodSignature") {
@@ -178,11 +162,8 @@ function resolveTargetNode(sourceCode, node) {
 }
 /**
  * Extract a direct Identifier name when available on the given node.
- * This focuses only on plain Identifier nodes and ignores container shapes.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Extract direct Identifier-based names from nodes
- * @param {any} node - AST node to inspect
- * @returns {string | null} identifier name or null when not applicable
  */
 function getDirectIdentifierName(node) {
     if (node &&
@@ -195,11 +176,8 @@ function getDirectIdentifierName(node) {
 }
 /**
  * Normalize container nodes that expose names via id/key properties.
- * Supports common function and method containers, including literal keys.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Normalize container id/key-based names into a single helper
- * @param {any} node - AST node that may contain id/key name information
- * @returns {string | null} resolved container name or null when unavailable
  */
 function getContainerKeyOrIdName(node) {
     if (!node) {
@@ -226,11 +204,8 @@ function getContainerKeyOrIdName(node) {
 }
 /**
  * Small utility to walk the node and its parents to extract an Identifier or key name.
- * Walks up the parent chain and inspects common properties (id, key, name, Identifier nodes).
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Walk node and parents to find Identifier/Key name
- * @param {any} node - AST node to extract a name from
- * @returns {string} extracted name or "(anonymous)" when no name found
  */
 function extractName(node) {
     let current = node;
@@ -251,15 +226,6 @@ function extractName(node) {
     }
     return "(anonymous)";
 }
-/**
- * Check if this node is within scope and matches exportPriority
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Determine whether a node should be processed by rule
- * @param {any} node - AST node to evaluate
- * @param {string[]} scope - allowed node types
- * @param {string} [exportPriority='all'] - 'all' | 'exported' | 'non-exported' (default: 'all')
- * @returns {boolean} whether node should be processed
- */
 function shouldProcessNode(node, scope, exportPriority = "all") {
     if (!scope.includes(node.type)) {
         return false;
@@ -275,11 +241,8 @@ function shouldProcessNode(node, scope, exportPriority = "all") {
 }
 /**
  * Resolve the effective function name to report for a node.
- * Normalizes id/key handling before delegating to extractName.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Centralize reported function name resolution
- * @param {any} node - AST node used to derive the function name
- * @returns {string} resolved function name
  */
 function getReportedFunctionName(node) {
     const candidate = node && (node.id || node.key) ? node.id || node.key : node;
@@ -287,11 +250,8 @@ function getReportedFunctionName(node) {
 }
 /**
  * Determine the most appropriate AST node to anchor error location for a report.
- * Prefers Identifier nodes from id/key properties when available.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Normalize name node selection for error reporting
- * @param {any} node - AST node used for error anchoring
- * @returns {any} node to use as the report location
  */
 function getNameNodeForReport(node) {
     if (node?.id?.type === "Identifier") {
@@ -307,27 +267,10 @@ function getNameNodeForReport(node) {
  * 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
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - original function-like AST node
- * @param {any} passedTarget - optional explicit annotation target
- * @returns {any} node that should receive the annotation
  */
 function resolveAnnotationTargetNode(sourceCode, node, passedTarget) {
     return passedTarget ?? resolveTargetNode(sourceCode, node);
 }
-/**
- * Build the effective annotation template and autofix toggle
- * from the provided report options.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Normalize template and autofix configuration
- * @param {ReportOptions} [options] - optional report configuration
- * @returns {{ effectiveTemplate: string; allowFix: boolean }} template and autofix flags
- */
-function buildTemplateConfig(options) {
-    const effectiveTemplate = getAnnotationTemplate(options?.annotationTemplateOverride);
-    const allowFix = shouldApplyAutoFix(options?.autoFixToggle);
-    return { effectiveTemplate, allowFix };
-}
 function reportMissing(context, sourceCode, config) {
     (0, require_story_core_1.coreReportMissing)({
         hasStoryAnnotation,

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-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;