/**
 * Copyright (c) 2026, Salesforce, Inc.,
 * All rights reserved.
 * For full license text, see the LICENSE.txt file
 */

import { type GraphQLSchema } from "graphql";
import { primeSchemaWithLock, type PrimeDeps } from "../lib/prime-schema.js";
import { getSchema } from "../lib/walker.js";

export interface SchemaWithPriming {
	schema: GraphQLSchema;
	instanceUrl: string;
	primingNote?: string;
}

/**
 * Resolve the schema for `orgAlias`, lazily priming the on-disk cache on miss.
 *
 * - Cache hit → `{ schema, instanceUrl }` only.
 * - Cache miss + auth resolves → introspects, writes cache, returns
 *   `{ schema, instanceUrl, primingNote: 'Note: Primed schema cache for "<org>" (took Nms)' }`.
 *   Callers thread the note into their `ToolOutput.warnings[]` per FR-13.3.
 * - Auth missing or introspection failure → throws (FR-13.5 / FR-13.6).
 *
 * The returned schema is loaded by instance URL (auth-free fast path), so the
 * cost of `getSchema(prime.instanceUrl)` is just a Map lookup after the first
 * call per process.
 */
export async function getSchemaWithPriming(
	orgAlias: string,
	deps?: PrimeDeps,
): Promise<SchemaWithPriming> {
	const prime = await primeSchemaWithLock(orgAlias, deps);
	const schema = getSchema(prime.instanceUrl);
	const base = { schema, instanceUrl: prime.instanceUrl };
	return prime.cached
		? base
		: {
				...base,
				primingNote: `Note: Primed schema cache for "${orgAlias}" (took ${prime.durationMs}ms)`,
			};
}