eslint-plugin-traceability 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -1,9 +1,14 @@
-# [1.21.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.20.0...v1.21.0) (2025-12-19)
+# [1.22.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.21.1...v1.22.0) (2026-01-10)
+
+
+### Bug Fixes
+
+* move voder-ai to optionalDependencies to allow CI without GitHub Packages access ([1a674cb](https://github.com/voder-ai/eslint-plugin-traceability/commit/1a674cb65d5223c75710910817393667435bfcd8))
 
 
 ### Features
 
-* support inside-brace placement for function-level rules ([064b1a4](https://github.com/voder-ai/eslint-plugin-traceability/commit/064b1a4e7627b5e35afd074752724ab5958e9d8b))
+* **ci:** add post-deployment verification step ([00d3d21](https://github.com/voder-ai/eslint-plugin-traceability/commit/00d3d214f21e18bfc26e3de4fbcb0bd9f0aa8f28))
 
 # Changelog
 

package/README.md

@@ -121,15 +121,15 @@ Traceability annotations are typically placed immediately adjacent to the code t
 
 - **Function-level (`traceability/require-story-annotation`, `traceability/require-req-annotation`)**
 
-  Function-level rules continue to accept annotations:
-  - As JSDoc blocks immediately preceding the function, or
-  - As line comments placed directly before the function declaration or expression.
+  Function-level rules support both before-function and inside-body placement, controlled by the same `annotationPlacement` option described above:
+  - `"before"` – Annotations are written as JSDoc blocks immediately preceding the function, or as line comments placed directly before the function declaration or expression.
+  - `"inside"` – Annotations are expected to appear on the first comment-only lines inside function and method bodies; comments before the function are ignored for block-bodied functions in this mode, while TypeScript declarations and signature-only nodes still rely on before-node annotations.
 
-  This placement is stable and supported for all current versions. Future versions may introduce an **inside-brace** placement mode for function bodies (similar to branch blocks) to align function annotations with the branch-level `"inside"` standard, but that behaviour is not yet implemented in the current release.
+  For full details and migration guidance between placement styles, see the [API Reference](user-docs/api-reference.md) and the migration guide ([user-docs/migration-guide.md](user-docs/migration-guide.md)).
 
 For full configuration details and migration guidance between placement styles, see:
 
-- `traceability/require-branch-annotation` rule docs: [docs/rules/require-branch-annotation.md](docs/rules/require-branch-annotation.md)
+- `traceability/require-branch-annotation` rule docs: [docs/rules/require-branch-annotation.md](https://github.com/voder-ai/eslint-plugin-traceability/blob/main/docs/rules/require-branch-annotation.md)
 - Migration guide: [user-docs/migration-guide.md](user-docs/migration-guide.md)
 
 ### Available Rules
@@ -280,7 +280,7 @@ Removing "duplicate" annotations would break the verification workflow by forcin
 
 ## Verification Workflow Guide
 
-For detailed verification workflows, examples, and best practices, see the [Verification Workflow Guide](docs/verification-workflow-guide.md).
+For detailed verification workflows, examples, and best practices, see the [Verification Workflow Guide](https://github.com/voder-ai/eslint-plugin-traceability/blob/main/docs/verification-workflow-guide.md).
 
 ## API Reference
 

package/lib/src/maintenance/batch.js

@@ -15,7 +15,6 @@ const detect_1 = require("./detect");
  */
 function batchUpdateAnnotations(codebasePath, mappings) {
     let totalUpdated = 0;
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-BATCH - Perform batch updates
     for (const { oldPath, newPath } of mappings) {
         totalUpdated += (0, update_1.updateAnnotationReferences)(codebasePath, oldPath, newPath);
     }

package/lib/src/maintenance/cli.js

@@ -19,7 +19,6 @@ function runMaintenanceCli(rawArgv) {
     const { subcommand: command } = initialNormalized;
     if (!command || command === "-h" || command === "--help") {
         // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Branch to show usage when no command or help flag is provided; handle help requests safely and provide discoverable usage output
         printHelp();
         return commands_1.EXIT_OK;
     }
@@ -28,35 +27,34 @@ function runMaintenanceCli(rawArgv) {
     const normalized = initialNormalized;
     try {
         // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Catch unexpected errors and surface concise diagnostics without crashing
         switch (command) {
             case "detect":
-                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT - Branch to dispatch to detection handler when 'detect' is requested; dispatch to detection handler
+                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
                 return (0, commands_1.handleDetect)(normalized);
             case "verify":
-                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY - Branch to dispatch to verification handler when 'verify' is requested; dispatch to verification handler
+                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY
                 return (0, commands_1.handleVerify)(normalized);
             case "report":
-                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT - Branch to dispatch to reporting handler when 'report' is requested; dispatch to reporting handler
+                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT
                 return (0, commands_1.handleReport)(normalized);
             case "update": {
-                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE - Branch to dispatch to update handler when 'update' is requested; dispatch to update handler
+                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
                 const result = (0, commands_1.handleUpdate)(normalized);
                 if (result === commands_1.EXIT_USAGE) {
-                    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Print help on usage errors from update; help branch for update usage errors
+                    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
                     printHelp();
                 }
                 return result;
             }
             default:
-                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Branch for unknown commands to emit diagnostics and safe usage guidance; handle unknown commands safely with diagnostics
+                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
                 console.error(`Unknown command: ${command}`);
                 printHelp();
                 return commands_1.EXIT_USAGE;
         }
     }
     catch (error) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Catch-all error branch to prevent crashes and provide concise diagnostics; catch unexpected errors and surface concise diagnostics without crashing
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
         const message = error instanceof Error
             ? error.message
             : "Unknown error in maintenance CLI";
@@ -70,7 +68,7 @@ function runMaintenanceCli(rawArgv) {
  * @req REQ-MAINT-SAFE - Provide discoverable CLI usage information
  */
 function printHelp() {
-    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Help branch ensures users can discover maintenance CLI usage safely; provide discoverable CLI usage information
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
     console.log(`traceability-maint - Traceability annotation maintenance tools
 
 Usage:

package/lib/src/maintenance/commands.d.ts

@@ -3,7 +3,7 @@ export declare const EXIT_OK = 0;
 export declare const EXIT_STALE = 1;
 export declare const EXIT_USAGE = 2;
 /**
- * Handle the `detect` subcommand for stale @story annotations.
+ * Handle the `detect` subcommand for stale story annotations.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
@@ -27,7 +27,7 @@ export declare function handleVerify(normalized: NormalizedCliArgs): number;
  */
 export declare function handleReport(normalized: NormalizedCliArgs): number;
 /**
- * Handle the `update` subcommand to rewrite @story annotation references.
+ * Handle the `update` subcommand to rewrite story annotation references.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
  * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks

package/lib/src/maintenance/commands.js

@@ -24,7 +24,7 @@ exports.EXIT_OK = 0;
 exports.EXIT_STALE = 1;
 exports.EXIT_USAGE = 2;
 /**
- * Handle the `detect` subcommand for stale @story annotations.
+ * Handle the `detect` subcommand for stale story annotations.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
@@ -95,7 +95,7 @@ function handleReport(normalized) {
     return exports.EXIT_OK;
 }
 /**
- * Handle the `update` subcommand to rewrite @story annotation references.
+ * Handle the `update` subcommand to rewrite story annotation references.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
  * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks

package/lib/src/maintenance/detect.js

@@ -84,7 +84,7 @@ function processFileForStaleAnnotations(file, workspaceRoot, cwd, stale) {
     }
     catch {
         // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Swallow file read failures without aborting detection
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
         return;
     }
     const regex = /@story\s+([^\s]+)/g;
@@ -115,7 +115,7 @@ function handleStoryMatch(storyPath, workspaceRoot, cwd, stale) {
     const inProjectCandidates = getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, workspaceRoot);
     // If both candidates are out-of-project, do not mark as stale and skip FS checks
     if (inProjectCandidates.length === 0) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT - No in-project candidates means nothing to check or mark stale
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         return;
     }
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -141,7 +141,7 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
     }
     catch {
         // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Treat boundary enforcement failures as out-of-project
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
         projectBoundary = {
             isWithinProject: false,
             candidate: storyProjectCandidate,
@@ -153,7 +153,7 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
     }
     catch {
         // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Treat boundary enforcement failures as out-of-project
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
         codebaseBoundary = {
             isWithinProject: false,
             candidate: storyCodebaseCandidate,
@@ -161,11 +161,11 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
     }
     const inProjectCandidates = [];
     if (projectBoundary.isWithinProject) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT - Collect project-relative in-project candidate
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         inProjectCandidates.push(projectBoundary.candidate);
     }
     if (codebaseBoundary.isWithinProject) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT - Collect workspace-root-relative in-project candidate
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         inProjectCandidates.push(codebaseBoundary.candidate);
     }
     return inProjectCandidates;
@@ -182,7 +182,7 @@ function anyInProjectCandidateExists(inProjectCandidates) {
     (p) => {
         const exists = fs.existsSync(p);
         if (!exists) {
-            // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Safely handle non-existent candidate without throwing
+            // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
         }
         return exists;
     });

package/lib/src/maintenance/report.js

@@ -12,8 +12,8 @@ const detect_1 = require("./detect");
  */
 function generateMaintenanceReport(codebasePath) {
     const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);
-    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - When no stale annotations are found, return empty string to indicate no actions required
-    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT - When stale annotations exist, produce a newline-separated report
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT
     if (staleAnnotations.length === 0) {
         return "";
     }

package/lib/src/maintenance/storyParser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Extract requirement IDs from story file content
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Parse story file content to identify available requirements
+ * @req REQ-DEEP-FORMAT - Support finding requirement IDs in multiple markdown contexts
+ * @req REQ-DEEP-SECTION - Handle requirements in different story file sections
+ */
+export declare function extractRequirementsFromStoryFile(filePath: string): Set<string>;
+/**
+ * Extract requirement IDs from story file content string
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Parse story file content to identify available requirements
+ * @req REQ-DEEP-FORMAT - Support finding requirement IDs in multiple markdown contexts
+ * @req REQ-DEEP-SECTION - Handle requirements in different story file sections
+ */
+export declare function extractRequirementsFromContent(content: string): Set<string>;

package/lib/src/maintenance/storyParser.js

@@ -0,0 +1,167 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRequirementsFromStoryFile = extractRequirementsFromStoryFile;
+exports.extractRequirementsFromContent = extractRequirementsFromContent;
+/**
+ * Parser for extracting requirements from story files
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Parse story file content to identify available requirements
+ * @req REQ-DEEP-FORMAT - Support finding requirement IDs in multiple markdown contexts
+ * @req REQ-DEEP-SECTION - Handle requirements in different story file sections
+ */
+const fs = __importStar(require("fs"));
+/**
+ * Extract requirement IDs from story file content
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Parse story file content to identify available requirements
+ * @req REQ-DEEP-FORMAT - Support finding requirement IDs in multiple markdown contexts
+ * @req REQ-DEEP-SECTION - Handle requirements in different story file sections
+ */
+function extractRequirementsFromStoryFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf8");
+        return extractRequirementsFromContent(content);
+    }
+    catch {
+        // @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+        // @req REQ-DEEP-PARSE - Handle file read errors gracefully
+        return new Set();
+    }
+}
+/**
+ * Extract requirement IDs from story file content string
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Parse story file content to identify available requirements
+ * @req REQ-DEEP-FORMAT - Support finding requirement IDs in multiple markdown contexts
+ * @req REQ-DEEP-SECTION - Handle requirements in different story file sections
+ */
+function extractRequirementsFromContent(content) {
+    const requirements = new Set();
+    // Strategy 1: Extract from structured sections (## Requirements, ## Acceptance Criteria)
+    // @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+    // @req REQ-DEEP-SECTION - Handle requirements in different story file sections
+    const sectionRequirements = extractFromSections(content);
+    sectionRequirements.forEach((req) => requirements.add(req));
+    // Strategy 2: Fallback to regex-based extraction for REQ-XXX-YYY patterns anywhere in file
+    // @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+    // @req REQ-DEEP-FORMAT - Support finding requirement IDs in multiple markdown contexts
+    const regexRequirements = extractWithRegex(content);
+    regexRequirements.forEach((req) => requirements.add(req));
+    return requirements;
+}
+/**
+ * Extract requirements from structured markdown sections
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-SECTION - Handle requirements in different story file sections
+ * @req REQ-DEEP-FORMAT - Support finding requirement IDs in multiple markdown contexts
+ */
+function extractFromSections(content) {
+    const requirements = new Set();
+    const lines = content.split("\n");
+    let inRequirementsSection = false;
+    let inAcceptanceCriteriaSection = false;
+    for (const line of lines) {
+        // Detect section headers
+        if (line.match(/^##\s+Requirements/i)) {
+            // @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+            // @req REQ-DEEP-SECTION - Parse ## Requirements sections
+            inRequirementsSection = true;
+            inAcceptanceCriteriaSection = false;
+            continue;
+        }
+        else if (line.match(/^##\s+Acceptance\s+Criteria/i)) {
+            // @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+            // @req REQ-DEEP-SECTION - Parse ## Acceptance Criteria sections
+            inAcceptanceCriteriaSection = true;
+            inRequirementsSection = false;
+            continue;
+        }
+        else if (line.match(/^##\s+/)) {
+            // New section that's not Requirements or Acceptance Criteria
+            inRequirementsSection = false;
+            inAcceptanceCriteriaSection = false;
+            continue;
+        }
+        // Extract requirements from active sections
+        if (inRequirementsSection || inAcceptanceCriteriaSection) {
+            // @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+            // @req REQ-DEEP-FORMAT - Extract requirement IDs from list items
+            const reqIds = extractReqIdsFromLine(line);
+            reqIds.forEach((req) => requirements.add(req));
+        }
+    }
+    return requirements;
+}
+/**
+ * Extract requirement IDs from a single line
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-FORMAT - Support finding requirement IDs in multiple markdown contexts
+ */
+function extractReqIdsFromLine(line) {
+    const requirements = [];
+    // Pattern 1: - **REQ-XXX-YYY**: Description
+    // @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+    // @req REQ-DEEP-FORMAT - Extract from bold requirement format
+    const boldPattern = /\*\*(REQ-[A-Z0-9-]+)\*\*/g;
+    let match;
+    while ((match = boldPattern.exec(line)) !== null) {
+        requirements.push(match[1]);
+    }
+    // Pattern 2: REQ-XXX-YYY anywhere in the line (not already captured)
+    // @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+    // @req REQ-DEEP-FORMAT - Extract from plain text mentions
+    const plainPattern = /\b(REQ-[A-Z0-9-]+)\b/g;
+    while ((match = plainPattern.exec(line)) !== null) {
+        if (!requirements.includes(match[1])) {
+            requirements.push(match[1]);
+        }
+    }
+    return requirements;
+}
+/**
+ * Extract requirements using regex fallback (for content outside structured sections)
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-FORMAT - Support finding requirement IDs in multiple markdown contexts
+ */
+function extractWithRegex(content) {
+    const requirements = new Set();
+    const regex = /\b(REQ-[A-Z0-9-]+)\b/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        requirements.add(match[1]);
+    }
+    return requirements;
+}

package/lib/src/rules/helpers/pattern-validators.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pattern validation helpers for valid-annotation-format options.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-REGEX-VALIDATION - Validate that configured patterns are valid regular expressions
+ */
+/**
+ * Build an error message for an invalid regex pattern.
+ *
+ * @supports docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md REQ-REGEX-VALIDATION
+ */
+export declare function buildInvalidRegexError(field: string, pattern: string): string;
+/**
+ * Arguments for the resolvePattern helper.
+ */
+export interface ResolvePatternArgs {
+    nestedPattern: string | undefined;
+    nestedFieldName: string;
+    flatPattern: string | undefined;
+    flatFieldName: string;
+    defaultPattern: RegExp;
+    errors?: string[];
+}
+/**
+ * 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
+ */
+export declare function resolvePattern({ nestedPattern, nestedFieldName, flatPattern, flatFieldName, defaultPattern, errors, }: ResolvePatternArgs): RegExp;
+/**
+ * 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
+ */
+export declare function resolveExample(nestedExample: string | undefined, flatExample: string | undefined, defaultExample: string): string;

package/lib/src/rules/helpers/pattern-validators.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Pattern validation helpers for valid-annotation-format options.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-REGEX-VALIDATION - Validate that configured patterns are valid regular expressions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildInvalidRegexError = buildInvalidRegexError;
+exports.resolvePattern = resolvePattern;
+exports.resolveExample = resolveExample;
+/**
+ * Build an error message for an invalid regex pattern.
+ *
+ * @supports docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md REQ-REGEX-VALIDATION
+ */
+function buildInvalidRegexError(field, pattern) {
+    return `Invalid regular expression for option "${field}": "${pattern}"`;
+}
+/**
+ * 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, errors, }) {
+    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 {
+        const error = buildInvalidRegexError(effective.field, effective.value);
+        if (errors) {
+            errors.push(error);
+        }
+        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;
+}

package/lib/src/rules/helpers/prefer-implements-inline.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Inline comment processing for prefer-implements-annotation rule.
+ * Handles migration of inline comment story and requirement patterns to supports format.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
+ * @req REQ-MIGRATE-INLINE
+ */
+import type { Rule } from "eslint";
+export type LineComment = {
+    type: "Line";
+} & any;
+/**
+ * Scan sequences of Line comments for inline legacy story and requirement patterns
+ * and report diagnostics with optional auto-fixes.
+ */
+export declare function processInlineComments(context: Rule.RuleContext, lineComments: LineComment[]): void;