eslint-plugin-traceability 1.10.1 → 1.11.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.10.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.10.0...v1.10.1) (2025-12-05)
+## [1.11.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.0...v1.11.1) (2025-12-05)
 
 
 ### Bug Fixes
 
-* support JSDoc tag coexistence for annotation parsing ([31e9416](https://github.com/voder-ai/eslint-plugin-traceability/commit/31e9416d201fd347051bc44521d3d3b840a244a1))
+* expose valid-annotation-format autofix toggle and align docs ([32e7636](https://github.com/voder-ai/eslint-plugin-traceability/commit/32e7636e9b8f784b84f694a13e9e06d6120e38b3))
 
 # Changelog
 

package/README.md

@@ -54,6 +54,7 @@ export default [
 - `traceability/valid-annotation-format` Enforces correct format of traceability annotations. (See the rule documentation in the plugin's user guide.)
 - `traceability/valid-story-reference` Validates that `@story` references point to existing story files. (See the rule documentation in the plugin's user guide.)
 - `traceability/valid-req-reference` Validates that `@req` references point to existing requirement IDs. (See the rule documentation in the plugin's user guide.)
+- `traceability/require-test-traceability` Enforces traceability conventions in test files by requiring file-level `@supports` annotations, story references in `describe` blocks, and `[REQ-...]` prefixes in `it`/`test` names. (See the rule documentation in the plugin's user guide.)
 - `traceability/prefer-implements-annotation` Recommends migration from legacy `@story`/`@req` annotations to `@supports` (opt-in; disabled by default in the presets and must be explicitly enabled). (See the rule documentation in the plugin's user guide.)
 
 Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in the plugin's user guide and the consolidated [API Reference](user-docs/api-reference.md).
@@ -82,7 +83,7 @@ export default [
 
 ```js
 /**
- * @story stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  *   // Point this to your own project's story/requirements file, not to this plugin's internal docs.
  * @req REQ-ANNOTATION-REQUIRED
  */
@@ -241,4 +242,4 @@ For the canonical, user-facing security policy (including how to report vulnerab
 - Contribution guide: <https://github.com/voder-ai/eslint-plugin-traceability/blob/main/CONTRIBUTING.md>
 - Issue tracker: <https://github.com/voder-ai/eslint-plugin-traceability/issues>
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
-- Versioning and Releases: This project uses semantic-release for automated versioning. The authoritative list of published versions and release notes is on GitHub Releases: <https://github.com/voder-ai/eslint-plugin-traceability/releases>
+- Versioning and Releases: This project uses semantic-release for automated versioning. The authoritative list of published versions and release notes is on GitHub Releases: <https://github.com/voder-ai/eslint-plugin-traceability/releases>

package/lib/src/maintenance/cli.js

@@ -18,8 +18,8 @@ function runMaintenanceCli(rawArgv) {
     const initialNormalized = (0, flags_1.normalizeCliArgs)(rawArgv);
     const { subcommand: command } = initialNormalized;
     if (!command || command === "-h" || command === "--help") {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
-        // @implements 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
+        // @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;
     }
@@ -27,36 +27,36 @@ function runMaintenanceCli(rawArgv) {
     // receive the subcommand name and its raw argument vector unchanged.
     const normalized = initialNormalized;
     try {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Catch unexpected errors and surface concise diagnostics without crashing
+        // @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":
-                // @implements 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 - Branch to dispatch to detection handler when 'detect' is requested; dispatch to detection handler
                 return (0, commands_1.handleDetect)(normalized);
             case "verify":
-                // @implements 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 - Branch to dispatch to verification handler when 'verify' is requested; dispatch to verification handler
                 return (0, commands_1.handleVerify)(normalized);
             case "report":
-                // @implements 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 - Branch to dispatch to reporting handler when 'report' is requested; dispatch to reporting handler
                 return (0, commands_1.handleReport)(normalized);
             case "update": {
-                // @implements 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 - Branch to dispatch to update handler when 'update' is requested; dispatch to update handler
                 const result = (0, commands_1.handleUpdate)(normalized);
                 if (result === commands_1.EXIT_USAGE) {
-                    // @implements 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 - Print help on usage errors from update; help branch for update usage errors
                     printHelp();
                 }
                 return result;
             }
             default:
-                // @implements 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 - Branch for unknown commands to emit diagnostics and safe usage guidance; handle unknown commands safely with diagnostics
                 console.error(`Unknown command: ${command}`);
                 printHelp();
                 return commands_1.EXIT_USAGE;
         }
     }
     catch (error) {
-        // @implements 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 - Catch-all error branch to prevent crashes and provide concise diagnostics; catch unexpected errors and surface concise diagnostics without crashing
         const message = error instanceof Error
             ? error.message
             : "Unknown error in maintenance CLI";
@@ -70,7 +70,7 @@ function runMaintenanceCli(rawArgv) {
  * @req REQ-MAINT-SAFE - Provide discoverable CLI usage information
  */
 function printHelp() {
-    // @implements 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 - Help branch ensures users can discover maintenance CLI usage safely; provide discoverable CLI usage information
     console.log(`traceability-maint - Traceability annotation maintenance tools
 
 Usage:

package/lib/src/maintenance/detect.js

@@ -54,9 +54,9 @@ function detectStaleAnnotations(codebasePath) {
     // @req REQ-MAINT-DETECT - Return empty result if workspaceRoot does not exist or is not a directory
     if (!fs.existsSync(workspaceRoot) ||
         !fs.statSync(workspaceRoot).isDirectory()) {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @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
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         return [];
     }
     const stale = new Set();
@@ -79,12 +79,12 @@ function processFileForStaleAnnotations(file, workspaceRoot, cwd, stale) {
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Handle file read errors gracefully
     try {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         content = fs.readFileSync(file, "utf8");
     }
     catch {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @implements 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-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Swallow file read failures without aborting detection
         return;
     }
     const regex = /@story\s+([^\s]+)/g;
@@ -103,7 +103,7 @@ function handleStoryMatch(storyPath, workspaceRoot, cwd, stale) {
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT REQ-SECURITY-VALIDATION - Skip traversal/absolute-unsafe or invalid-extension story paths before any filesystem or boundary checks
     if ((0, storyReferenceUtils_1.isUnsafeStoryPath)(storyPath)) {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         return;
     }
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -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) {
-        // @implements 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 - No in-project candidates means nothing to check or mark stale
         return;
     }
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -124,7 +124,7 @@ function handleStoryMatch(storyPath, workspaceRoot, cwd, stale) {
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Mark story as stale if any in-project candidate exists conceptually but none exist on disk
     if (!anyExists) {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         stale.add(storyPath);
     }
 }
@@ -136,24 +136,24 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
     let projectBoundary;
     let codebaseBoundary;
     try {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         projectBoundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(storyProjectCandidate, workspaceRoot);
     }
     catch {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @implements 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-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Treat boundary enforcement failures as out-of-project
         projectBoundary = {
             isWithinProject: false,
             candidate: storyProjectCandidate,
         };
     }
     try {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         codebaseBoundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(storyCodebaseCandidate, workspaceRoot);
     }
     catch {
-        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @implements 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-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Treat boundary enforcement failures as out-of-project
         codebaseBoundary = {
             isWithinProject: false,
             candidate: storyCodebaseCandidate,
@@ -161,11 +161,11 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
     }
     const inProjectCandidates = [];
     if (projectBoundary.isWithinProject) {
-        // @implements 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 - Collect project-relative in-project candidate
         inProjectCandidates.push(projectBoundary.candidate);
     }
     if (codebaseBoundary.isWithinProject) {
-        // @implements 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 - Collect workspace-root-relative in-project candidate
         inProjectCandidates.push(codebaseBoundary.candidate);
     }
     return inProjectCandidates;
@@ -177,12 +177,12 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
 function anyInProjectCandidateExists(inProjectCandidates) {
     return inProjectCandidates.some(
     /**
-     * @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
+     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
      */
     (p) => {
         const exists = fs.existsSync(p);
         if (!exists) {
-            // @implements 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 - Safely handle non-existent candidate without throwing
         }
         return exists;
     });

package/lib/src/maintenance/flags.js

@@ -60,43 +60,129 @@ function createDefaultFlags() {
     };
 }
 /**
- * Handle a single CLI argument and update the flags accordingly.
+ * Safely check if the next argument value exists and is a string.
  *
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
  */
-function applyFlag(flags, args, index) {
-    const arg = args[index];
-    if (arg === "--root" && typeof args[index + 1] === "string") {
-        flags.root = path_1.default.resolve(args[index + 1]);
-        return index + 1;
+function isNextValueString(args, index) {
+    return typeof args[index + 1] === "string";
+}
+/**
+ * Handle the --root flag, updating the root path if present.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function handleRootFlag(flags, args, index) {
+    if (args[index] !== "--root" || !isNextValueString(args, index)) {
+        return index;
+    }
+    flags.root = path_1.default.resolve(args[index + 1]);
+    return index + 1;
+}
+/**
+ * Handle the --json flag, toggling JSON output when present.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function handleJsonFlag(flags, args, index) {
+    if (args[index] !== "--json") {
+        return index;
     }
-    if (arg === "--json") {
-        flags.json = true;
+    flags.json = true;
+    return index;
+}
+/**
+ * Handle the --format flag, validating and setting the output format.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function handleFormatFlag(flags, args, index) {
+    if (args[index] !== "--format" || !isNextValueString(args, index)) {
         return index;
     }
-    if (arg === "--format" && typeof args[index + 1] === "string") {
-        const value = args[index + 1];
-        if (value === "text" || value === "json") {
-            flags.format = value;
-        }
-        else {
-            throw new Error(`Invalid format: ${value}. Expected 'text' or 'json'.`);
-        }
-        return index + 1;
+    const value = args[index + 1];
+    if (value === "text" || value === "json") {
+        flags.format = value;
+    }
+    else {
+        throw new Error(`Invalid format: ${value}. Expected 'text' or 'json'.`);
     }
-    if (arg === "--from" && typeof args[index + 1] === "string") {
-        flags.from = args[index + 1];
-        return index + 1;
+    return index + 1;
+}
+/**
+ * Handle the --from flag, capturing the starting reference if present.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function handleFromFlag(flags, args, index) {
+    if (args[index] !== "--from" || !isNextValueString(args, index)) {
+        return index;
     }
-    if (arg === "--to" && typeof args[index + 1] === "string") {
-        flags.to = args[index + 1];
-        return index + 1;
+    flags.from = args[index + 1];
+    return index + 1;
+}
+/**
+ * Handle the --to flag, capturing the ending reference if present.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function handleToFlag(flags, args, index) {
+    if (args[index] !== "--to" || !isNextValueString(args, index)) {
+        return index;
     }
-    if (arg === "--dry-run") {
-        flags.dryRun = true;
+    flags.to = args[index + 1];
+    return index + 1;
+}
+/**
+ * Handle the --dry-run flag, enabling dry-run mode when present.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function handleDryRunFlag(flags, args, index) {
+    if (args[index] !== "--dry-run") {
         return index;
     }
+    flags.dryRun = true;
+    return index;
+}
+/**
+ * Handle a single CLI argument and update the flags accordingly.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function applyFlag(flags, args, index) {
+    const afterRoot = handleRootFlag(flags, args, index);
+    if (afterRoot !== index) {
+        return afterRoot;
+    }
+    const afterJson = handleJsonFlag(flags, args, index);
+    if (afterJson !== index) {
+        return afterJson;
+    }
+    const afterFormat = handleFormatFlag(flags, args, index);
+    if (afterFormat !== index) {
+        return afterFormat;
+    }
+    const afterFrom = handleFromFlag(flags, args, index);
+    if (afterFrom !== index) {
+        return afterFrom;
+    }
+    const afterTo = handleToFlag(flags, args, index);
+    if (afterTo !== index) {
+        return afterTo;
+    }
+    const afterDryRun = handleDryRunFlag(flags, args, index);
+    if (afterDryRun !== index) {
+        return afterDryRun;
+    }
     return index;
 }
 /**

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

@@ -1,35 +1,81 @@
-import type { Rule } from "eslint";
 /**
  * Create a fixer function that inserts a @story annotation before the target node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Provide automatic fix function for missing @story annotations
  */
-export declare function createAddStoryFix(target: any): (fixer: any) => any;
+export declare function createAddStoryFix(target: any, annotationTemplate: string): (fixer: any) => any;
 /**
  * Create a fixer function for class method annotations.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
  */
-export declare function createMethodFix(node: any): (fixer: any) => any;
+export declare function createMethodFix(node: any, annotationTemplate: string): (fixer: any) => any;
 /**
  * Default set of node types to check for missing @story annotations.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Provide sensible default scope for rule checks
  */
 export declare const DEFAULT_SCOPE: string[];
+/**
+ * Path to the story file for function-annotation helpers.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Provide a single source of truth for the canonical story path used by helper modules
+ */
+export declare const STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
 /**
  * Allowed values for export priority option.
  */
 export declare const EXPORT_PRIORITY_VALUES: string[];
+import type { Rule } from "eslint";
+type CoreReportOptions = {
+    annotationTemplateOverride?: string;
+    autoFixToggle?: boolean;
+};
+type ReportDeps = {
+    hasStoryAnnotation: (_sourceCode: any, _node: any) => boolean;
+    getReportedFunctionName: (_node: any) => string;
+    resolveAnnotationTargetNode: (_sourceCode: any, _node: any, _passedTarget: any) => any;
+    getNameNodeForReport: (_node: any) => any;
+    buildTemplateConfig: (_options?: CoreReportOptions) => {
+        effectiveTemplate: string;
+        allowFix: boolean;
+    };
+    extractName: (_node: any) => string;
+    getAnnotationTemplate: (_override?: string) => string;
+    shouldApplyAutoFix: (_autoFix: boolean | undefined) => boolean;
+    createAddStoryFix: (_target: any, _annotationTemplate: string) => any;
+    createMethodFix: (_node: any, _annotationTemplate: string) => any;
+};
 /**
- * Report a missing @story annotation for a general function-like node.
+ * Core helper to report a missing @story annotation for a function-like node.
+ * Delegates actual behavior to injected dependencies so higher-level helpers
+ * can remain small while sharing error-reporting behavior.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-AUTOFIX - Report missing annotation and provide autofix using createAddStoryFix
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-AUTOFIX-MISSING
+ * @req REQ-ERROR-SPECIFIC
  */
-export declare function reportMissing(context: Rule.RuleContext, sourceCode: any, node: any, target?: any): void;
+export declare function coreReportMissing(deps: ReportDeps, context: Rule.RuleContext, sourceCode: any, config: {
+    node: any;
+    target?: any;
+    options?: CoreReportOptions;
+}): void;
 /**
- * Report missing @story annotation for methods
+ * Core helper to report a missing @story annotation for a method-like node.
+ * Delegates actual behavior to injected dependencies while keeping this
+ * module focused on core error-reporting behavior.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-AUTOFIX-MISSING
+ * @req REQ-ERROR-SPECIFIC
  */
-export declare function reportMethod(context: Rule.RuleContext, sourceCode: any, node: any, target?: any): void;
+export declare function coreReportMethod(deps: ReportDeps, context: Rule.RuleContext, sourceCode: any, config: {
+    node: any;
+    target?: any;
+    options?: CoreReportOptions;
+}): void;
+export {};