feat: implement smart title search and inline comments separation

- Add hybrid title search that attempts exact match first, then falls back to partial matching using CQL
- Implement new inline comments tool (conf_ls_inline_comments) for filtering inline-only comments
- Add comprehensive error handling for CQL compatibility issues (space.id vs space.key)
- Transform search results to proper pages format for seamless integration
- Maintain backward compatibility for exact title matches
- Update tool descriptions to reflect SMART MATCHING capabilities

BREAKING CHANGE: Title search behavior now includes automatic partial matching fallback

Author: aashari

src/controllers/atlassian.comments.controller.ts

@@ -11,6 +11,7 @@ import {
 } from '../utils/pagination.util.js';
 import { ControllerResponse } from '../types/common.types.js';
 import { formatCommentsList } from './atlassian.comments.formatter.js';
+import { formatInlineCommentsList } from './atlassian.inline-comments.formatter.js';
 import { DEFAULT_PAGE_SIZE } from '../utils/defaults.util.js';
 import { adfToMarkdown } from '../utils/adf.util.js';
 import {
@@ -49,6 +50,41 @@ interface ListPageCommentsOptions {
 	bodyFormat?: 'storage' | 'view' | 'atlas_doc_format';
 }
 
+/**
+ * Interface for list inline comments options
+ */
+interface ListInlineCommentsOptions {
+	/**
+	 * The ID of the page to get inline comments for
+	 */
+	pageId: string;
+
+	/**
+	 * Include resolved inline comments
+	 */
+	includeResolved?: boolean;
+
+	/**
+	 * Sort order for inline comments
+	 */
+	sortBy?: 'created' | 'position';
+
+	/**
+	 * Maximum number of results to return
+	 */
+	limit?: number;
+
+	/**
+	 * Starting point for pagination
+	 */
+	start?: number;
+
+	/**
+	 * Body format (storage, view, atlas_doc_format)
+	 */
+	bodyFormat?: 'storage' | 'view' | 'atlas_doc_format';
+}
+
 /**
  * Extended interface for a comment with converted markdown content
  */
@@ -206,7 +242,184 @@ async function listPageComments(
 	}
 }
 
+/**
+ * List inline comments only for a specific Confluence page
+ *
+ * @param options - Options for listing inline comments
+ * @returns Controller response with formatted inline comments and pagination info
+ */
+async function listInlineComments(
+	options: ListInlineCommentsOptions,
+): Promise<ControllerResponse> {
+	const methodLogger = logger.forMethod('listInlineComments');
+	try {
+		// Apply defaults and prepare service parameters
+		const {
+			pageId,
+			includeResolved = false,
+			sortBy = 'position',
+			limit = DEFAULT_PAGE_SIZE,
+			start = 0,
+			bodyFormat = 'atlas_doc_format',
+		} = options;
+
+		methodLogger.debug('Listing inline comments for page', {
+			pageId,
+			includeResolved,
+			sortBy,
+			limit,
+			start,
+			bodyFormat,
+		});
+
+		// Get all comments first with a higher limit to ensure we capture inline comments
+		// since we'll filter them locally
+		const allCommentsData = await atlassianCommentsService.listPageComments(
+			{
+				pageId,
+				limit: 250, // Get more comments to filter inline ones
+				start: 0, // Always start from beginning for inline filtering
+				bodyFormat,
+			},
+		);
+
+		methodLogger.debug('Retrieved all comments for filtering', {
+			totalComments: allCommentsData.results.length,
+			pageId,
+		});
+
+		// Filter for inline comments only
+		const inlineCommentsRaw = allCommentsData.results.filter((comment) => {
+			const isInline = comment.extensions?.location === 'inline';
+
+			// Apply resolved filter if needed
+			if (!includeResolved && comment.status !== 'current') {
+				return false;
+			}
+
+			return isInline;
+		});
+
+		methodLogger.debug('Filtered inline comments', {
+			inlineCount: inlineCommentsRaw.length,
+			totalCount: allCommentsData.results.length,
+			includeResolved,
+		});
+
+		// Convert ADF content to Markdown and extract highlighted text for inline comments
+		const convertedComments: CommentWithContext[] = inlineCommentsRaw.map(
+			(comment) => {
+				let markdownBody =
+					'*Content format not supported or unavailable*';
+
+				// Convert comment body from ADF to Markdown
+				if (comment.body?.atlas_doc_format?.value) {
+					try {
+						markdownBody = adfToMarkdown(
+							comment.body.atlas_doc_format.value,
+						);
+						methodLogger.debug(
+							`Successfully converted ADF to Markdown for inline comment ${comment.id}`,
+						);
+					} catch (conversionError) {
+						methodLogger.error(
+							`ADF conversion failed for inline comment ${comment.id}`,
+							conversionError,
+						);
+						// Keep default error message
+					}
+				} else {
+					methodLogger.warn(
+						`No ADF content available for inline comment ${comment.id}`,
+					);
+				}
+
+				// Extract the highlighted text for inline comments
+				let highlightedText: string | undefined = undefined;
+				if (comment.extensions?.inlineProperties) {
+					// Safely access inlineProperties fields with type checking
+					const props = comment.extensions
+						.inlineProperties as InlineProperties;
+
+					// Try different properties that might contain the highlighted text
+					highlightedText =
+						props.originalSelection || props.textContext;
+
+					// If not found in standard properties, check for custom properties
+					if (!highlightedText && 'selectionText' in props) {
+						highlightedText = String(props.selectionText || '');
+					}
+
+					if (highlightedText) {
+						methodLogger.debug(
+							`Found highlighted text for inline comment ${comment.id}: ${highlightedText.substring(0, 50)}${highlightedText.length > 50 ? '...' : ''}`,
+						);
+					} else {
+						methodLogger.warn(
+							`No highlighted text found for inline comment ${comment.id}`,
+						);
+					}
+				}
+
+				// Return comment with added context
+				return {
+					...comment,
+					convertedMarkdownBody: markdownBody,
+					highlightedText,
+				};
+			},
+		);
+
+		// Sort inline comments by requested order
+		if (sortBy === 'position') {
+			convertedComments.sort((a, b) => {
+				// Sort by marker position or container ID if available
+				const aPos = a.extensions?.inlineProperties?.markerRef || a.id;
+				const bPos = b.extensions?.inlineProperties?.markerRef || b.id;
+				return String(aPos).localeCompare(String(bPos));
+			});
+		} else if (sortBy === 'created') {
+			// Sort by ID as a proxy for creation order (newer IDs = later created)
+			convertedComments.sort((a, b) => a.id.localeCompare(b.id));
+		}
+
+		// Apply pagination after filtering and sorting
+		const paginatedComments = convertedComments.slice(start, start + limit);
+
+		methodLogger.debug('Applied pagination to inline comments', {
+			totalInline: convertedComments.length,
+			start,
+			limit,
+			returned: paginatedComments.length,
+		});
+
+		// Format the inline comments for display
+		const baseUrl = allCommentsData._links?.base || '';
+		const formattedContent = formatInlineCommentsList(
+			paginatedComments,
+			pageId,
+			baseUrl,
+			convertedComments.length,
+			start,
+			limit,
+		);
+
+		return {
+			content: formattedContent,
+		};
+	} catch (error) {
+		// Handle errors
+		throw handleControllerError(error, {
+			entityType: 'InlineComment',
+			operation: 'list',
+			source: 'controllers/atlassian.comments.controller.ts@listInlineComments',
+			additionalInfo: { pageId: options.pageId },
+		});
+	}
+}
+
 // Export controller functions
 export const atlassianCommentsController = {
 	listPageComments,
+	listInlineComments,
 };