eslint-plugin-traceability 1.11.0 → 1.11.1

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.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.0...v1.11.1) (2025-12-05)
 
 
-### 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))
+* expose valid-annotation-format autofix toggle and align docs ([32e7636](https://github.com/voder-ai/eslint-plugin-traceability/commit/32e7636e9b8f784b84f694a13e9e06d6120e38b3))
 
 # 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
  */
@@ -242,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/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

@@ -16,7 +16,66 @@ export declare function createMethodFix(node: any, annotationTemplate: string):
  * @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;
+};
+/**
+ * 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
+ * @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.
+ * 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
+ * @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,8 +1,10 @@
 "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;
 /**
  * Create a fixer function that inserts a @story annotation before the target node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -69,7 +71,95 @@ exports.DEFAULT_SCOPE = [
     "TSMethodSignature",
     "TSDeclareFunction",
 ];
+/**
+ * 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
+ */
+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.
+ * 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
+ * @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 {
+        /* noop */
+    }
+}
+/**
+ * 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
+ * @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 {
+        /* noop */
+    }
+}

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

@@ -10,11 +10,7 @@
 import type { Rule } from "eslint";
 import { linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory } from "./require-story-io";
 import { getNodeName } from "./require-story-utils";
-import { DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES } from "./require-story-core";
-/**
- * Path to the story file for annotations
- */
-declare const STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
+import { DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, STORY_PATH } from "./require-story-core";
 /**
  * Derive the annotation template, optionally using an override.
  * When override is a non-empty string, its trimmed value is used.
@@ -26,18 +22,6 @@ declare function getAnnotationTemplate(override?: string): string;
  * Explicit false disables auto-fix; all other values enable it.
  */
 declare function shouldApplyAutoFix(autoFix: boolean | undefined): boolean;
-/**
- * Number of physical source lines to inspect before a node when searching for @story text
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Replace magic number for lookback lines with named constant
- */
-declare const LOOKBACK_LINES = 4;
-/**
- * Window (in characters) to inspect before a node as a fallback when searching for @story text
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Replace magic number for fallback text window with named constant
- */
-declare const FALLBACK_WINDOW = 800;
 /**
  * Determine if a node is in an export declaration
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -114,40 +98,11 @@ interface ReportOptions {
     annotationTemplateOverride?: string;
     autoFixToggle?: boolean;
 }
-/**
- * Report a missing @story annotation for a function-like node
- * Provides a suggestion to add the annotation.
- * @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 - Implement reporting for missing annotations with suggestion
- * @req REQ-AUTOFIX-MISSING - Provide autofix for missing annotations while preserving suggestions
- * @req REQ-ERROR-SPECIFIC - Error reports must include both name and functionName in the data payload for specific function context
- * @param {Rule.RuleContext} context - ESLint rule context used to report
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {{ node: any; target?: any; options?: ReportOptions }} config - configuration containing the node to report, optional insertion target, and optional report options
- */
 declare function reportMissing(context: Rule.RuleContext, sourceCode: any, config: {
     node: any;
     target?: any;
     options?: ReportOptions;
 }): void;
-/**
- * Report a missing @story annotation for a method-like node
- * Provides a suggestion to update the method/interface with the annotation.
- * The error data payload uses both name and functionName for consistent, specific error context.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
- * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing method/interface annotations with suggestion
- * @req REQ-AUTOFIX-MISSING - Provide autofix for missing method/interface annotations while preserving suggestions
- * @req REQ-ERROR-SPECIFIC - Method error reports must include both name and functionName in the data payload for specific function context
- * @req REQ-ERROR-LOCATION - Method error reports must use the method name node to anchor error location
- * @req REQ-ERROR-CONTEXT - Method error reports must include functionName data for consistent error context
- * @param {Rule.RuleContext} context - ESLint rule context to report
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {{ node: any; target?: any; options?: ReportOptions }} config - configuration containing the node to report, optional insertion target, and optional report options
- */
 declare function reportMethod(context: Rule.RuleContext, sourceCode: any, config: {
     node: any;
     target?: any;
@@ -158,4 +113,4 @@ declare function reportMethod(context: Rule.RuleContext, sourceCode: any, config
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Explicitly export helper functions and constants used by requiring modules
  */
-export { STORY_PATH, getAnnotationTemplate, shouldApplyAutoFix, LOOKBACK_LINES, FALLBACK_WINDOW, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, extractName, resolveTargetNode, shouldProcessNode, reportMissing, reportMethod, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, };
+export { STORY_PATH, getAnnotationTemplate, shouldApplyAutoFix, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, extractName, resolveTargetNode, shouldProcessNode, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, reportMissing, reportMethod, };