eslint-plugin-traceability 1.9.0 → 1.10.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.9.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.8.3...v1.9.0) (2025-12-04)
+## [1.10.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.10.0...v1.10.1) (2025-12-05)
 
 
-### Features
+### Bug Fixes
 
-* add require-test-traceability rule for test files ([1eca595](https://github.com/voder-ai/eslint-plugin-traceability/commit/1eca595d7c1b12b224c3b7a647405c0bff7e7346))
+* support JSDoc tag coexistence for annotation parsing ([31e9416](https://github.com/voder-ai/eslint-plugin-traceability/commit/31e9416d201fd347051bc44521d3d3b840a244a1))
 
 # Changelog
 

package/lib/src/rules/helpers/require-test-traceability-helpers.d.ts

@@ -0,0 +1,34 @@
+export type TestTraceabilityAutoFixOptions = {
+    autoFixTestTemplate: boolean;
+    testSupportsTemplate?: string;
+};
+export type CallExpressionOptions = {
+    sourceCode: any;
+    describeRegex: RegExp;
+    requireDescribeStory: boolean;
+    requireTestReqPrefix: boolean;
+    autoFixTestPrefixFormat: boolean;
+};
+/**
+ * Determine if a file should be treated as a test file based on patterns.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT
+ */
+export declare function determineIsTestFile(filename: string, rawPatterns?: string[]): boolean;
+/**
+ * Ensure the file has a @supports annotation listing tested requirements.
+ *
+ * When auto-fix is enabled, a placeholder @supports JSDoc is inserted at the
+ * top of the file (after any shebang) using a safe, non-semantic template.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS REQ-TEST-SUPPORTS-VALID
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PLACEHOLDER REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+export declare function ensureFileSupportsAnnotation(context: any, sourceCode: any, autoFixOptions: TestTraceabilityAutoFixOptions): void;
+/**
+ * Build a CallExpression visitor for the main rule create() function.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX REQ-TEST-NESTED-DESCRIBE REQ-TEST-ERROR-CONTEXT
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+export declare function handleCallExpression(context: any, options: CallExpressionOptions): (node: any) => void;

package/lib/src/rules/helpers/require-test-traceability-helpers.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.determineIsTestFile = determineIsTestFile;
+exports.ensureFileSupportsAnnotation = ensureFileSupportsAnnotation;
+exports.handleCallExpression = handleCallExpression;
+/**
+ * Helper utilities for the require-test-traceability rule.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT REQ-TEST-FRAMEWORK-COMPAT
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-PLACEHOLDER REQ-TEST-FIX-NO-INFERENCE
+ */
+const NOT_FOUND = -1;
+const REQ_PREFIX_LENGTH = 3;
+const QUOTES = ["'", '"', "`"];
+/**
+ * Determine if a file should be treated as a test file based on patterns.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT
+ */
+function determineIsTestFile(filename, rawPatterns = [
+    "/tests/",
+    "/test/",
+    "/__tests__",
+    ".test.",
+    ".spec.",
+]) {
+    return rawPatterns.some((pattern) => filename.includes(pattern.replace("**", "")));
+}
+/**
+ * Build the placeholder @supports template comment for a test file.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PLACEHOLDER
+ */
+function buildSupportsTemplateComment(customTemplate) {
+    const baseTemplate = (customTemplate && customTemplate.trim()) ||
+        "@supports docs/stories/XXX.X-STORY-NAME.story.md REQ-XXX-YYY REQ-XXX-ZZZ";
+    const lines = [
+        "/**",
+        ` * ${baseTemplate}`,
+        " * TODO: Replace the placeholder story path and REQ-IDs with real values for this test file.",
+        " */",
+        "",
+    ];
+    return lines.join("\n");
+}
+/**
+ * Insert the file-level @supports template comment at a safe location.
+ *
+ * The template is inserted after a shebang line if present, otherwise at the
+ * very start of the file. This preserves executable semantics while adding
+ * only comment text.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+function insertSupportsTemplate(fixer, sourceCode, customTemplate) {
+    const text = sourceCode.text || "";
+    let insertIndex = 0;
+    // Preserve shebang: it must remain the very first characters in the file.
+    if (text.startsWith("#!")) {
+        const firstNewline = text.indexOf("\n");
+        insertIndex = firstNewline === NOT_FOUND ? text.length : firstNewline + 1;
+    }
+    const templateComment = buildSupportsTemplateComment(customTemplate);
+    return fixer.insertTextBeforeRange([insertIndex, insertIndex], templateComment);
+}
+/**
+ * Ensure the file has a @supports annotation listing tested requirements.
+ *
+ * When auto-fix is enabled, a placeholder @supports JSDoc is inserted at the
+ * top of the file (after any shebang) using a safe, non-semantic template.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS REQ-TEST-SUPPORTS-VALID
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PLACEHOLDER REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+function ensureFileSupportsAnnotation(context, sourceCode, autoFixOptions) {
+    const fileComments = sourceCode.getAllComments() || [];
+    const fileHasSupports = fileComments.some((comment) => /@supports\b/.test(comment.value || ""));
+    if (!fileHasSupports) {
+        const node = fileComments[0] || (sourceCode.ast && sourceCode.ast);
+        context.report({
+            node: node,
+            messageId: "missingFileSupports",
+            fix: autoFixOptions.autoFixTestTemplate === false
+                ? undefined
+                : (fixer) => insertSupportsTemplate(fixer, sourceCode, autoFixOptions.testSupportsTemplate),
+        });
+    }
+}
+/**
+ * Check if a callee name corresponds to a test framework function.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FRAMEWORK-COMPAT
+ */
+function isTestCallName(name) {
+    return ["describe", "it", "test", "context"].includes(name);
+}
+function getCalleeName(node) {
+    if (node.callee.type === "Identifier") {
+        return node.callee.name;
+    }
+    if (node.callee.type === "MemberExpression" &&
+        node.callee.object.type === "Identifier") {
+        return node.callee.object.name;
+    }
+    return null;
+}
+function getFirstArgumentLiteral(node) {
+    const arg = node.arguments && node.arguments[0];
+    if (!arg)
+        return null;
+    if (arg.type === "Literal" && typeof arg.value === "string") {
+        return arg.value;
+    }
+    return null;
+}
+/**
+ * Normalize a raw REQ identifier string to canonical REQ-XXX format.
+ *
+ * This helper performs only local, format-level normalization without
+ * inferring new requirement IDs.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-NO-INFERENCE
+ */
+function normalizeReqId(raw) {
+    let id = raw.trim().toUpperCase();
+    if (!id.startsWith("REQ")) {
+        return id;
+    }
+    let rest = id.slice(REQ_PREFIX_LENGTH);
+    // Drop leading separators after "REQ"
+    rest = rest.replace(/^[-_\s:]+/, "");
+    // Convert internal whitespace/underscores to hyphens
+    rest = rest.replace(/[\s_]+/g, "-");
+    // Collapse multiple hyphens
+    rest = rest.replace(/-+/g, "-");
+    return rest ? `REQ-${rest}` : "REQ-";
+}
+/**
+ * Normalize malformed [REQ-XXX] prefixes in test names.
+ *
+ * Handles cases such as:
+ * - "[ REQ-XXX ] ..."  -> "[REQ-XXX] ..."
+ * - "[REQ_XXX] ..."    -> "[REQ-XXX] ..."
+ * - "(REQ-XXX) ..."    -> "[REQ-XXX] ..."
+ * - "[req-xxx] ..."    -> "[REQ-XXX] ..."
+ *
+ * Only operates when a REQ identifier is already present at the start of the
+ * string; it never invents new IDs.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+function normalizeReqPrefixInDescription(description) {
+    const canonicalPattern = /^\[REQ-[^\]]+]/;
+    if (canonicalPattern.test(description)) {
+        return null;
+    }
+    // Leading square brackets with optional spacing.
+    const squareMatch = description.match(/^\[\s*(REQ[^\]]*?)\s*](.*)$/i);
+    if (squareMatch) {
+        const normalizedId = normalizeReqId(squareMatch[1]);
+        return `[${normalizedId}]${squareMatch[2] ?? ""}`;
+    }
+    // Leading parentheses with optional spacing.
+    const parenMatch = description.match(/^\(\s*(REQ[^)]*?)\s*\)(.*)$/i);
+    if (parenMatch) {
+        const normalizedId = normalizeReqId(parenMatch[1]);
+        return `[${normalizedId}]${parenMatch[2] ?? ""}`;
+    }
+    return null;
+}
+/**
+ * Create a string literal with the same quote style as the original node.
+ *
+ * This helper rewrites only the literal value while preserving the original
+ * quoting character (`'`, `"`, or `` ` ``) and escaping rules.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PRESERVE
+ */
+function createUpdatedStringLiteralRaw(originalNode, newValue, sourceCode) {
+    const raw = sourceCode.getText(originalNode);
+    const firstChar = raw[0];
+    if (QUOTES.includes(firstChar)) {
+        const quote = firstChar;
+        const escaped = newValue
+            .replace(/\\/g, "\\\\")
+            .replace(new RegExp(`\\${quote}`, "g"), `\\${quote}`);
+        return `${quote}${escaped}${quote}`;
+    }
+    // Fallback: let JSON.stringify choose a safe representation.
+    return JSON.stringify(newValue);
+}
+function handleDescribeCall(context, node, description, options) {
+    const { describeRegex, requireDescribeStory } = options;
+    if (!requireDescribeStory)
+        return;
+    if (!describeRegex.test(description)) {
+        context.report({
+            node: node,
+            messageId: "missingDescribeStory",
+        });
+    }
+}
+function handleItOrTestCall(context, node, description, options) {
+    const { sourceCode, requireTestReqPrefix, autoFixTestPrefixFormat } = options;
+    if (!requireTestReqPrefix)
+        return;
+    if (!/^\[REQ-[^\]]+]/.test(description)) {
+        const normalizedDescription = autoFixTestPrefixFormat !== false
+            ? normalizeReqPrefixInDescription(description)
+            : null;
+        context.report({
+            node: node,
+            messageId: "missingReqPrefix",
+            ...(autoFixTestPrefixFormat !== false &&
+                normalizedDescription !== null &&
+                node.arguments &&
+                node.arguments[0] &&
+                node.arguments[0].type === "Literal" &&
+                typeof node.arguments[0].value === "string"
+                ? {
+                    fix(fixer) {
+                        const literalNode = node.arguments[0];
+                        const newRaw = createUpdatedStringLiteralRaw(literalNode, normalizedDescription, sourceCode);
+                        return fixer.replaceText(literalNode, newRaw);
+                    },
+                }
+                : {}),
+        });
+    }
+}
+/**
+ * Build a CallExpression visitor for the main rule create() function.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX REQ-TEST-NESTED-DESCRIBE REQ-TEST-ERROR-CONTEXT
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+function handleCallExpression(context, options) {
+    const { describeRegex, requireDescribeStory } = options;
+    return (node) => {
+        const calleeName = getCalleeName(node);
+        if (!calleeName || !isTestCallName(calleeName)) {
+            return;
+        }
+        const description = getFirstArgumentLiteral(node);
+        if (!description)
+            return;
+        if (calleeName === "describe") {
+            handleDescribeCall(context, node, description, {
+                describeRegex,
+                requireDescribeStory,
+            });
+            return;
+        }
+        if (calleeName === "it" || calleeName === "test") {
+            handleItOrTestCall(context, node, description, options);
+        }
+    };
+}

package/lib/src/rules/helpers/valid-annotation-format-internal.d.ts

@@ -28,3 +28,14 @@ export interface PendingAnnotation {
  * of the line for downstream logic.
  */
 export declare function normalizeCommentLine(rawLine: string): string;
+/**
+ * Detect whether a normalized comment line starts with a non-traceability JSDoc tag.
+ *
+ * This is used to distinguish regular JSDoc tags (e.g. @param, @returns) from
+ * traceability-related annotations such as @story, @req, and @supports.
+ *
+ * @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
+ * @req REQ-JSDOC-BOUNDARY-DETECTION
+ * @req REQ-JSDOC-TAG-COEXISTENCE
+ */
+export declare function isNonTraceabilityJSDocTagLine(normalized: string): boolean;

package/lib/src/rules/helpers/valid-annotation-format-internal.js

@@ -13,6 +13,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeCommentLine = normalizeCommentLine;
+exports.isNonTraceabilityJSDocTagLine = isNonTraceabilityJSDocTagLine;
 /**
  * Normalize a raw comment line to make annotation parsing more robust.
  *
@@ -34,3 +35,23 @@ function normalizeCommentLine(rawLine) {
     }
     return trimmed.slice(annotationMatch.index);
 }
+/**
+ * Detect whether a normalized comment line starts with a non-traceability JSDoc tag.
+ *
+ * This is used to distinguish regular JSDoc tags (e.g. @param, @returns) from
+ * traceability-related annotations such as @story, @req, and @supports.
+ *
+ * @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
+ * @req REQ-JSDOC-BOUNDARY-DETECTION
+ * @req REQ-JSDOC-TAG-COEXISTENCE
+ */
+function isNonTraceabilityJSDocTagLine(normalized) {
+    const trimmed = normalized.trimStart();
+    if (!trimmed || !trimmed.startsWith("@")) {
+        return false;
+    }
+    if (/^@(story|req|supports)\b/.test(trimmed)) {
+        return false;
+    }
+    return true;
+}

package/lib/src/rules/helpers/valid-annotation-format-validators.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Validators and helper functions for the valid-annotation-format rule.
+ *
+ * This module contains the core validation logic that was originally
+ * embedded in src/rules/valid-annotation-format.ts. It is extracted
+ * here to keep the main rule module smaller and easier to read while
+ * preserving existing behavior.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-SPECIFICATION
+ * @req REQ-SYNTAX-VALIDATION
+ * @req REQ-PATH-FORMAT
+ * @req REQ-REQ-FORMAT
+ * @req REQ-MULTILINE-SUPPORT
+ * @req REQ-AUTOFIX-FORMAT
+ * @req REQ-ERROR-SPECIFICITY
+ * @req REQ-REGEX-VALIDATION
+ * @req REQ-BACKWARD-COMP
+ * @req REQ-SUPPORTS-PARSE
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+import type { ResolvedAnnotationOptions } from "./valid-annotation-options";
+import type { PendingAnnotation } from "./valid-annotation-format-internal";
+/**
+ * Report an invalid @story annotation without applying a fix.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+export declare function reportInvalidStoryFormat(context: any, comment: any, collapsed: string, options: ResolvedAnnotationOptions): void;
+/**
+ * Compute the text replacement for an invalid @story annotation within a comment.
+ *
+ * This helper:
+ *   - finds the @story tag in the raw comment text,
+ *   - computes the character range of its value,
+ *   - and returns an ESLint fix that replaces only that range.
+ *
+ * Returns null when the tag or value cannot be safely located.
+ *
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-SAFE
+ * @req REQ-AUTOFIX-PRESERVE
+ */
+export declare function createStoryFix(context: any, comment: any, fixed: string): null | (() => any);
+/**
+ * Report an invalid @story annotation and attempt a minimal, safe auto-fix
+ * for common path suffix issues by locating and replacing the path text
+ * within the original comment.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and avoid changing semantics
+ * @req REQ-AUTOFIX-PRESERVE - Auto-fix must preserve surrounding formatting and comments
+ */
+export declare function reportInvalidStoryFormatWithFix(context: any, comment: any, collapsed: string, fixed: string): void;
+/**
+ * Validate a @story annotation value and report detailed errors when needed.
+ * Where safe and unambiguous, apply an automatic fix for missing suffixes.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-REGEX-VALIDATION - Validate configurable story regex patterns and fall back safely
+ * @req REQ-BACKWARD-COMP - Preserve behavior when invalid regex config is supplied
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+export declare function validateStoryAnnotation(context: any, comment: any, rawValue: string, options: ResolvedAnnotationOptions): void;
+/**
+ * Validate a @req annotation value and report detailed errors when needed.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ * @req REQ-REGEX-VALIDATION - Validate configurable requirement regex patterns and fall back safely
+ * @req REQ-BACKWARD-COMP - Preserve behavior when invalid regex config is supplied
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+export declare function validateReqAnnotation(context: any, comment: any, rawValue: string, options: ResolvedAnnotationOptions): void;
+/**
+ * Validate an @supports annotation value and report detailed errors when needed.
+ *
+ * Expected format:
+ *   @supports <storyPath> <REQ-ID> [<REQ-ID> ...]
+ *
+ * Validation rules:
+ *   - Value must include at least a story path and one requirement ID.
+ *   - Story path must match the same storyPattern used for @story (no auto-fix).
+ *   - Each subsequent token must match reqPattern and is validated individually.
+ *
+ * Story path issues are reported with "invalidImplementsFormat" and
+ * requirement ID issues reuse the existing "invalidReqFormat" message.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-SUPPORTS-PARSE - Parse @supports annotations without affecting @story/@req
+ * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+export declare function validateImplementsAnnotation(context: any, comment: any, rawValue: string, options: ResolvedAnnotationOptions): void;
+/**
+ * Finalize and validate the currently pending annotation, if any.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+export declare function finalizePendingAnnotation(context: any, comment: any, options: ResolvedAnnotationOptions, pending: PendingAnnotation | null): PendingAnnotation | null;