eslint-plugin-traceability 1.11.0 → 1.11.2

package/CHANGELOG.md

@@ -1,10 +1,9 @@
-# [1.11.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.10.1...v1.11.0) (2025-12-05)
+## [1.11.2](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.1...v1.11.2) (2025-12-06)
 
 
-### Features
+### Bug Fixes
 
-* add configurable auto-fix templates and toggles ([5e0e6e7](https://github.com/voder-ai/eslint-plugin-traceability/commit/5e0e6e782812aebb128c4922931bb9703265bfb1))
-* add configurable auto-fix templates and toggles ([21c3a79](https://github.com/voder-ai/eslint-plugin-traceability/commit/21c3a79ce2e2e7fd95a422a963735d67940c8bd8))
+* ignore inline-code annotation references in comment normalization ([118d743](https://github.com/voder-ai/eslint-plugin-traceability/commit/118d743ff8c8bf1dcb0854b898480c641cc727c8))
 
 # Changelog
 

package/README.md

@@ -83,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
  */

package/lib/src/index.d.ts

@@ -11,16 +11,27 @@ import type { Rule } from "eslint";
  */
 import { detectStaleAnnotations, updateAnnotationReferences, batchUpdateAnnotations, verifyAnnotations, generateMaintenanceReport } from "./maintenance";
 /**
- * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
  * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
  */
 declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference", "prefer-implements-annotation", "require-test-traceability"];
 type RuleName = (typeof RULE_NAMES)[number];
 declare const rules: Record<RuleName, Rule.RuleModule>;
+/**
+ * Plugin metadata used by ESLint for debugging and caching.
+ *
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE REQ-NPM-PACKAGE
+ */
+declare const pluginMeta: {
+    readonly name: string;
+    readonly version: string;
+    readonly namespace: "traceability";
+};
 declare const plugin: {
     rules: typeof rules;
     configs?: unknown;
     maintenance?: unknown;
+    meta?: typeof pluginMeta;
 };
 /**
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md

package/lib/src/index.js

@@ -7,7 +7,7 @@ exports.maintenance = exports.configs = exports.rules = void 0;
  */
 const maintenance_1 = require("./maintenance");
 /**
- * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
  * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
  */
 const RULE_NAMES = [
@@ -24,18 +24,18 @@ const rules = {};
 exports.rules = rules;
 RULE_NAMES.forEach(
 /**
- * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
  * @req REQ-DYNAMIC-LOADING - Support dynamic rule loading by name at runtime
  * @param {RuleName} name - Rule file base name used to discover and load rule module
  */
 (name) => {
     /**
-     * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
+     * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
      * @req REQ-DYNAMIC-LOADING - Support dynamic rule loading by name at runtime
      */
     try {
         /**
-         * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
+         * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
          * @req REQ-DYNAMIC-LOADING - Support dynamic rule loading by name at runtime
          */
         // Dynamically require rule module
@@ -45,11 +45,11 @@ RULE_NAMES.forEach(
     }
     catch (error) {
         /**
-         * @story docs/stories/003.0-RULE-LOAD-ERROR-HANDLING.story.md
+         * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
          * @req REQ-ERROR-HANDLING - Provide fallback rule module and surface errors when rule loading fails
          */
         /**
-         * @story docs/stories/003.0-RULE-LOAD-ERROR-HANDLING.story.md
+         * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
          * @req REQ-ERROR-HANDLING - Provide fallback rule module and surface errors when rule loading fails
          */
         console.error(`[eslint-plugin-traceability] Failed to load rule "${name}": ${error.message}`);
@@ -74,8 +74,45 @@ RULE_NAMES.forEach(
         };
     }
 });
+/**
+ * Plugin metadata used by ESLint for debugging and caching.
+ *
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE REQ-NPM-PACKAGE
+ */
+const pluginMeta = (() => {
+    let pkg = {};
+    try {
+        // When running from built output (lib/src/index.js)
+        // this resolves to the package.json at the project root.
+        // @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-NPM-PACKAGE
+        pkg = require("../../package.json");
+    }
+    catch {
+        try {
+            // When running via the TypeScript sources (src/index.ts) in this repo,
+            // fall back to resolving package.json one level up from src/.
+            // @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-NPM-PACKAGE
+            pkg = require("../package.json");
+        }
+        catch {
+            // As a last resort (tests, unusual environments), provide sensible
+            // defaults so that plugin loading never fails just for metadata.
+            // @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE
+            pkg = {
+                name: "eslint-plugin-traceability",
+                version: "0.0.0-development",
+            };
+        }
+    }
+    return {
+        name: pkg.name ?? "eslint-plugin-traceability",
+        version: pkg.version ?? "0.0.0-development",
+        namespace: "traceability",
+    };
+})();
 const plugin = {
     rules,
+    meta: pluginMeta,
 };
 /**
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md

package/lib/src/maintenance/commands.js

@@ -9,7 +9,7 @@ exports.handleUpdate = handleUpdate;
  * Subcommand handlers for the traceability-maint CLI.
  *
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - CLI support for detection of stale annotations
+ * @req REQ-MAINT-DETECT - CLI support for detection of stale annotations.
  * @req REQ-MAINT-VERIFY - CLI support for verification of annotations
  * @req REQ-MAINT-REPORT - CLI support for human-readable reports
  * @req REQ-MAINT-UPDATE - CLI support for updating annotation references
@@ -34,8 +34,7 @@ function handleDetect(normalized) {
     const root = flags.root;
     const stale = (0, detect_1.detectStaleAnnotations)(root);
     if (flags.json) {
-        // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-        // @req REQ-MAINT-REPORT - JSON-friendly output for tooling integration
+        // Emit JSON output to support consumption by external tools and scripts.
         console.log(JSON.stringify({ root, stale }));
     }
     else if (stale.length === 0) {

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/maintenance/update.js

@@ -42,20 +42,7 @@ const utils_1 = require("./utils");
  * @req REQ-MAINT-UPDATE
  */
 function processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCountRef) {
-    const stat = fs.statSync(fullPath);
-    /**
-     * Skip non-files in iteration
-     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-     * @req REQ-MAINT-UPDATE
-     */
-    /**
-     * Skip entries that are not regular files (e.g., directories)
-     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-     * @req REQ-MAINT-UPDATE
-     */
-    if (!stat.isFile())
-        return;
-    const content = fs.readFileSync(fullPath, "utf8");
+    const content = fs.readFileSync(fullPath, "utf8"); // getAllFiles already returns regular files
     const newContent = content.replace(regex, 
     /**
      * Replacement callback to update annotation references

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

@@ -1,22 +1,89 @@
 /**
  * Create a fixer function that inserts a @story annotation before the target node.
+ * This fixer is responsible for placing the annotation immediately before the
+ * resolved target node in the source code.
  * @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, annotationTemplate: string): (fixer: any) => any;
 /**
  * Create a fixer function for class method annotations.
+ * This helper ensures that the @story annotation is inserted with appropriate
+ * indentation and placement before a class method declaration.
  * @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, annotationTemplate: string): (fixer: any) => any;
 /**
  * Default set of node types to check for missing @story annotations.
+ * This default scope covers common function-like declarations used in typical
+ * TypeScript and JavaScript codebases.
  * @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.
+ * This constant centralizes the reference to the canonical documentation story
+ * used by these 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;
+};
+/**
+ * Core helper to report a missing @story annotation for a function-like node.
+ * This reporting utility delegates behavior to injected dependencies so that
+ * higher-level helpers can stay small while sharing error-reporting logic.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @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 coreReportMissing(deps: ReportDeps, context: Rule.RuleContext, sourceCode: any, config: {
+    node: any;
+    target?: any;
+    options?: CoreReportOptions;
+}): void;
+/**
+ * Core helper to report a missing @story annotation for a method-like node.
+ * This method-focused reporting utility uses injected dependencies while
+ * keeping this module centered on core error-reporting behavior.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @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 coreReportMethod(deps: ReportDeps, context: Rule.RuleContext, sourceCode: any, config: {
+    node: any;
+    target?: any;
+    options?: CoreReportOptions;
+}): void;
+export {};

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

@@ -1,64 +1,81 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = void 0;
+exports.EXPORT_PRIORITY_VALUES = exports.STORY_PATH = exports.DEFAULT_SCOPE = void 0;
 exports.createAddStoryFix = createAddStoryFix;
 exports.createMethodFix = createMethodFix;
+exports.coreReportMissing = coreReportMissing;
+exports.coreReportMethod = coreReportMethod;
+/**
+ * Compute the insertion start offset for inserting annotations before a node.
+ * This helper ensures we insert before any export wrapper when present, while
+ * remaining resilient to malformed or unexpected AST structures.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX
+ * @req REQ-AUTOFIX-SAFE
+ */
+function getInsertionStart(candidate) {
+    if (!candidate || typeof candidate !== "object") {
+        return 0;
+    }
+    const parent = candidate.parent;
+    if (parent &&
+        (parent.type === "ExportNamedDeclaration" ||
+            parent.type === "ExportDefaultDeclaration") &&
+        Array.isArray(parent.range) &&
+        typeof parent.range[0] === "number") {
+        return parent.range[0];
+    }
+    if (Array.isArray(candidate.range) &&
+        typeof candidate.range[0] === "number") {
+        return candidate.range[0];
+    }
+    return 0;
+}
 /**
  * Create a fixer function that inserts a @story annotation before the target node.
+ * This fixer is responsible for placing the annotation immediately before the
+ * resolved target node in the source code.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Provide automatic fix function for missing @story annotations
  */
 function createAddStoryFix(target, annotationTemplate) {
     /**
      * Fixer that inserts a @story annotation before the target node.
+     * This inner fixer is used by ESLint to apply the actual code modification.
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
      * @req REQ-AUTOFIX - Provide automatic fix function for missing @story annotations
      */
     function addStoryFixer(fixer) {
-        const start = target && typeof target === "object"
-            ? target.parent &&
-                (target.parent.type === "ExportNamedDeclaration" ||
-                    target.parent.type === "ExportDefaultDeclaration") &&
-                Array.isArray(target.parent.range) &&
-                typeof target.parent.range[0] === "number"
-                ? target.parent.range[0]
-                : Array.isArray(target.range) && typeof target.range[0] === "number"
-                    ? target.range[0]
-                    : 0
-            : 0;
+        const start = getInsertionStart(target);
         return fixer.insertTextBeforeRange([start, start], `${annotationTemplate}\n`);
     }
     return addStoryFixer;
 }
 /**
  * Create a fixer function for class method annotations.
+ * This helper ensures that the @story annotation is inserted with appropriate
+ * indentation and placement before a class method declaration.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
  */
 function createMethodFix(node, annotationTemplate) {
     /**
      * Fixer that inserts a @story annotation before a method node.
+     * This inner fixer handles inserting the annotation with method-friendly
+     * formatting and spacing.
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
      * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
      */
     function methodFixer(fixer) {
-        const start = node && typeof node === "object"
-            ? node.parent &&
-                (node.parent.type === "ExportNamedDeclaration" ||
-                    node.parent.type === "ExportDefaultDeclaration") &&
-                Array.isArray(node.parent.range) &&
-                typeof node.parent.range[0] === "number"
-                ? node.parent.range[0]
-                : Array.isArray(node.range) && typeof node.range[0] === "number"
-                    ? node.range[0]
-                    : 0
-            : 0;
+        const start = getInsertionStart(node);
         return fixer.insertTextBeforeRange([start, start], `${annotationTemplate}\n  `);
     }
     return methodFixer;
 }
 /**
  * Default set of node types to check for missing @story annotations.
+ * This default scope covers common function-like declarations used in typical
+ * TypeScript and JavaScript codebases.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Provide sensible default scope for rule checks
  */
@@ -69,7 +86,109 @@ exports.DEFAULT_SCOPE = [
     "TSMethodSignature",
     "TSDeclareFunction",
 ];
+/**
+ * Path to the story file for function-annotation helpers.
+ * This constant centralizes the reference to the canonical documentation story
+ * used by these 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
+ */
+exports.STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
 /**
  * Allowed values for export priority option.
  */
 exports.EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
+/**
+ * Core helper to report a missing @story annotation for a function-like node.
+ * This reporting utility delegates behavior to injected dependencies so that
+ * higher-level helpers can stay small while sharing error-reporting logic.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @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
+ */
+function coreReportMissing(deps, context, sourceCode, config) {
+    const { node, target: passedTarget, options = {} } = config;
+    try {
+        if (deps.hasStoryAnnotation(sourceCode, node)) {
+            return;
+        }
+        const functionName = deps.getReportedFunctionName(node);
+        const resolvedTarget = deps.resolveAnnotationTargetNode(sourceCode, node, passedTarget);
+        const nameNode = deps.getNameNodeForReport(node);
+        const { effectiveTemplate, allowFix } = deps.buildTemplateConfig(options);
+        const name = functionName;
+        context.report({
+            node: nameNode,
+            messageId: "missingStory",
+            data: { name, functionName: name },
+            fix: allowFix
+                ? deps.createAddStoryFix(resolvedTarget, effectiveTemplate)
+                : undefined,
+            suggest: [
+                {
+                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
+                    fix: deps.createAddStoryFix(resolvedTarget, effectiveTemplate),
+                },
+            ],
+        });
+    }
+    catch (error) {
+        // Intentionally swallow unexpected helper errors so traceability checks never
+        // break lint runs. When TRACEABILITY_DEBUG=1 is set, log a debug message to
+        // help diagnose misbehaving helpers in local development without affecting
+        // normal CI or production usage.
+        if (process.env.TRACEABILITY_DEBUG === "1") {
+            console.error("[traceability] coreReportMissing failed for node", error?.message ?? error);
+        }
+    }
+}
+/**
+ * Core helper to report a missing @story annotation for a method-like node.
+ * This method-focused reporting utility uses injected dependencies while
+ * keeping this module centered on core error-reporting behavior.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @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
+ */
+function coreReportMethod(deps, context, sourceCode, config) {
+    const { node, target: passedTarget, options = {} } = config;
+    try {
+        if (deps.hasStoryAnnotation(sourceCode, node)) {
+            return;
+        }
+        const resolvedTarget = passedTarget ?? deps.resolveAnnotationTargetNode(sourceCode, node, null);
+        const name = deps.extractName(node);
+        const nameNode = (node.key && node.key.type === "Identifier" && node.key) || node;
+        const effectiveTemplate = deps.getAnnotationTemplate(options.annotationTemplateOverride);
+        const allowFix = deps.shouldApplyAutoFix(options.autoFixToggle);
+        context.report({
+            node: nameNode,
+            messageId: "missingStory",
+            data: { name, functionName: name },
+            fix: allowFix
+                ? deps.createMethodFix(resolvedTarget, effectiveTemplate)
+                : undefined,
+            suggest: [
+                {
+                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
+                    fix: deps.createMethodFix(resolvedTarget, effectiveTemplate),
+                },
+            ],
+        });
+    }
+    catch (error) {
+        // Intentionally swallow unexpected helper errors so traceability checks never
+        // break lint runs. When TRACEABILITY_DEBUG=1 is set, log a debug message to
+        // help diagnose misbehaving helpers in local development without affecting
+        // normal CI or production usage.
+        if (process.env.TRACEABILITY_DEBUG === "1") {
+            console.error("[traceability] coreReportMethod failed for node", error?.message ?? error);
+        }
+    }
+}