// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.

import type { ApiItem } from '../items/ApiItem.js';

/**
 * Generic result object for finding API items used by different kinds of find operations.
 *
 * @public
 */
export interface IFindApiItemsResult {
	/**
	 * The API items that were found. Not guaranteed to be complete, see `maybeIncompleteResult`.
	 */
	items: ApiItem[];

	/**
	 * Indicates whether the result is potentially incomplete due to errors during the find operation.
	 * If true, the `messages` explain the errors in more detail.
	 */
	maybeIncompleteResult: boolean;

	/**
	 * Diagnostic messages regarding the find operation.
	 */
	messages: IFindApiItemsMessage[];
}

/**
 * This object is used for messages returned as part of `IFindApiItemsResult`.
 *
 * @public
 */
export interface IFindApiItemsMessage {
	/**
	 * Unique identifier for the message.
	 *
	 * @beta
	 */
	messageId: FindApiItemsMessageId;

	/**
	 * Text description of the message.
	 */
	text: string;
}

/**
 * Unique identifiers for messages returned as part of `IFindApiItemsResult`.
 *
 * @public
 */
export enum FindApiItemsMessageId {
	/**
	 * "Unable to resolve declaration reference within API item ___: ___"
	 */
	DeclarationResolutionFailed = 'declaration-resolution-failed',

	/**
	 * "Unable to analyze extends clause ___ of API item ___ because no canonical reference was found."
	 */
	ExtendsClauseMissingReference = 'extends-clause-missing-reference',

	/**
	 * "Unable to analyze references of API item ___ because it is not associated with an ApiModel"
	 */
	NoAssociatedApiModel = 'no-associated-api-model',

	/**
	 * "Unable to analyze references of API item ___ because it is of unsupported kind ___"
	 */
	UnsupportedKind = 'unsupported-kind',
}