@salesforce/graphiti 10.10.2

package/src/lib/introspect.ts

@@ -0,0 +1,320 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- graphiti traverses untyped schema/introspection JSON; see follow-up to replace with `unknown` + narrowing */
+
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { Org, type Connection } from "@salesforce/core";
+import type { OrgAuth } from "./auth.js";
+import { atomicWriteJson, graphitiHome } from "./fs-utils.js";
+
+// Re-export for backward compatibility with existing graphiti consumers.
+export { graphitiHome };
+
+/** API version used for display-only endpoints where no live connection is available
+ *  to query the org's actual version (live requests use connection.getApiVersion()). */
+export const DEFAULT_API_VERSION = "67.0";
+
+async function getConnection(auth: OrgAuth): Promise<Connection> {
+	const org = await Org.create({ aliasOrUsername: auth.alias });
+	return org.getConnection();
+}
+
+/** Resolves the directory holding cached introspection JSON files. */
+export function schemaDir(): string {
+	return path.join(graphitiHome(), "schemas");
+}
+
+const INTROSPECTION_QUERY = `
+query IntrospectionQuery {
+  __schema {
+    queryType { name }
+    mutationType { name }
+    types {
+      kind
+      name
+      description
+      fields(includeDeprecated: false) {
+        name
+        description
+        args {
+          name
+          description
+          type { ...TypeRef }
+          defaultValue
+        }
+        type { ...TypeRef }
+      }
+      inputFields {
+        name
+        description
+        type { ...TypeRef }
+        defaultValue
+      }
+      interfaces { ...TypeRef }
+      enumValues(includeDeprecated: false) {
+        name
+        description
+      }
+      possibleTypes { ...TypeRef }
+    }
+    directives {
+      name
+      description
+      locations
+      args {
+        name
+        description
+        type { ...TypeRef }
+        defaultValue
+      }
+    }
+  }
+}
+
+fragment TypeRef on __Type {
+  kind
+  name
+  ofType {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+        ofType {
+          kind
+          name
+          ofType {
+            kind
+            name
+            ofType {
+              kind
+              name
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+
+// ── DLM/SSOT stripping ───────────────────────────────────────────────────────
+
+const DLM_SSOT_RE = /__dlm/i;
+
+function getNamedTypeNameFromRef(typeRef: any): string | null {
+	if (!typeRef) return null;
+	if (typeRef.name) return typeRef.name;
+	return getNamedTypeNameFromRef(typeRef.ofType);
+}
+
+/**
+ * Strips Data Cloud (DLM/SSOT) types and their field references from a raw
+ * introspection result.  Matches type names containing `__dlm` (case-insensitive)
+ * or starting with `ssot__`.  Returns the mutated result and a count of removed types.
+ */
+export function stripDataCloudTypes(raw: any): { result: any; removedCount: number } {
+	const schema = raw?.data?.__schema ?? raw?.__schema;
+	if (!schema?.types) return { result: raw, removedCount: 0 };
+
+	const removedNames = new Set<string>();
+	for (const type of schema.types) {
+		if (type.name && (DLM_SSOT_RE.test(type.name) || type.name.startsWith("ssot__"))) {
+			removedNames.add(type.name);
+		}
+	}
+
+	if (removedNames.size === 0) return { result: raw, removedCount: 0 };
+
+	const isRemoved = (ref: any) => {
+		const name = getNamedTypeNameFromRef(ref);
+		return name != null && removedNames.has(name);
+	};
+
+	schema.types = schema.types.filter((t: any) => !removedNames.has(t.name));
+
+	for (const type of schema.types) {
+		if (type.fields) {
+			type.fields = type.fields.filter((f: any) => !isRemoved(f.type));
+		}
+		if (type.inputFields) {
+			type.inputFields = type.inputFields.filter((f: any) => !isRemoved(f.type));
+		}
+		if (type.possibleTypes) {
+			type.possibleTypes = type.possibleTypes.filter(
+				(t: any) => !t.name || !removedNames.has(t.name),
+			);
+		}
+		if (type.interfaces) {
+			type.interfaces = type.interfaces.filter((t: any) => !t.name || !removedNames.has(t.name));
+		}
+	}
+
+	return { result: raw, removedCount: removedNames.size };
+}
+
+function _schemaPath(alias: string): string {
+	return path.join(schemaDir(), `${alias}.json`);
+}
+
+export function normalizeInstanceUrl(instanceUrl: string): string {
+	return instanceUrl.replace(/\/+$/, "").toLowerCase();
+}
+
+export function schemaCacheKeyForInstanceUrl(instanceUrl: string): string {
+	const normalized = normalizeInstanceUrl(instanceUrl);
+	return crypto.createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}
+
+function schemaPathForInstanceUrl(instanceUrl: string): string {
+	const cacheKey = schemaCacheKeyForInstanceUrl(instanceUrl);
+	return path.join(schemaDir(), `${cacheKey}.json`);
+}
+
+export function schemaExists(instanceUrl: string): boolean {
+	return fs.existsSync(schemaPathForInstanceUrl(normalizeInstanceUrl(instanceUrl)));
+}
+
+export interface SchemaMetadata {
+	cacheKey: string;
+	instanceUrl: string;
+	typeCount: number;
+	downloadedAt: string;
+	filePath: string;
+	strippedDataCloudTypes?: number;
+}
+
+export function getSchemaMetadata(instanceUrl: string): SchemaMetadata | null {
+	const normalized = normalizeInstanceUrl(instanceUrl);
+	const fp = schemaPathForInstanceUrl(normalized);
+	if (!fs.existsSync(fp)) return null;
+	try {
+		const raw = JSON.parse(fs.readFileSync(fp, "utf-8"));
+		const types = (raw?.data?.__schema?.types ?? raw?.__schema?.types ?? []) as any[];
+		const stat = fs.statSync(fp);
+		return {
+			cacheKey: schemaCacheKeyForInstanceUrl(normalized),
+			instanceUrl: normalized,
+			typeCount: types.filter((t: any) => !t.name.startsWith("__")).length,
+			downloadedAt: stat.mtime.toISOString(),
+			filePath: fp,
+		};
+	} catch {
+		return null;
+	}
+}
+
+export function listCachedSchemas(): SchemaMetadata[] {
+	const dir = schemaDir();
+	if (!fs.existsSync(dir)) return [];
+	return fs
+		.readdirSync(dir)
+		.filter((f) => f.endsWith(".json"))
+		.map((fileName) => {
+			try {
+				const fp = path.join(dir, fileName);
+				const raw = JSON.parse(fs.readFileSync(fp, "utf-8"));
+				const types = (raw?.data?.__schema?.types ?? raw?.__schema?.types ?? []) as any[];
+				const stat = fs.statSync(fp);
+				const instanceUrl = raw?.__graphiti?.instanceUrl;
+				if (typeof instanceUrl !== "string") return null;
+				return {
+					cacheKey: fileName.replace(".json", ""),
+					instanceUrl,
+					typeCount: types.filter((t: any) => !t.name.startsWith("__")).length,
+					downloadedAt: stat.mtime.toISOString(),
+					filePath: fp,
+				};
+			} catch {
+				return null;
+			}
+		})
+		.filter((m): m is SchemaMetadata => m !== null);
+}
+
+export async function downloadSchema(auth: OrgAuth): Promise<SchemaMetadata> {
+	const connection = await getConnection(auth);
+	const url = `${auth.instanceUrl}/services/data/v${connection.getApiVersion()}/graphql`;
+
+	const rawResult = (await connection.request({
+		method: "POST",
+		url,
+		body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+		headers: { "Content-Type": "application/json", "X-Chatter-Entity-Encoding": "false" },
+	})) as any;
+
+	if (rawResult?.errors?.length) {
+		const messages = (rawResult.errors as any[])
+			.map((e: any) => e.message ?? JSON.stringify(e))
+			.join("\n  ");
+		throw new Error(`Introspection query returned errors:\n  ${messages}`);
+	}
+
+	const rawSchema = rawResult?.data?.__schema ?? rawResult?.__schema;
+	if (!rawSchema) {
+		throw new Error("Introspection query did not return a __schema field");
+	}
+
+	const { result, removedCount } = stripDataCloudTypes(rawResult);
+	const schema = result?.data?.__schema ?? result?.__schema;
+
+	const instanceUrl = normalizeInstanceUrl(auth.instanceUrl);
+	const filePath = schemaPathForInstanceUrl(instanceUrl);
+	const payload = {
+		...result,
+		__graphiti: {
+			instanceUrl,
+			alias: auth.alias,
+			cachedAt: new Date().toISOString(),
+			cacheKey: schemaCacheKeyForInstanceUrl(instanceUrl),
+			strippedDataCloudTypes: removedCount,
+		},
+	};
+	atomicWriteJson(filePath, payload);
+
+	const typeCount = (schema.types as any[]).filter((t: any) => !t.name.startsWith("__")).length;
+
+	return {
+		cacheKey: schemaCacheKeyForInstanceUrl(instanceUrl),
+		instanceUrl,
+		typeCount,
+		downloadedAt: new Date().toISOString(),
+		filePath,
+		strippedDataCloudTypes: removedCount || undefined,
+	};
+}
+
+export function loadIntrospectionResult(instanceUrl: string): any {
+	const fp = schemaPathForInstanceUrl(normalizeInstanceUrl(instanceUrl));
+	if (!fs.existsSync(fp)) {
+		throw new Error(`No cached schema for "${instanceUrl}". Run \`graphiti connect <org>\` first.`);
+	}
+	return JSON.parse(fs.readFileSync(fp, "utf-8"));
+}
+
+/** Returns the absolute path to the cached introspection JSON file. */
+export function getSchemaFilePath(instanceUrl: string): string {
+	return schemaPathForInstanceUrl(normalizeInstanceUrl(instanceUrl));
+}
+
+export async function executeGraphQL(
+	auth: OrgAuth,
+	query: string,
+	variables?: Record<string, unknown>,
+): Promise<any> {
+	const connection = await getConnection(auth);
+	const url = `${auth.instanceUrl}/services/data/v${connection.getApiVersion()}/graphql`;
+	return connection.request({
+		method: "POST",
+		url,
+		body: JSON.stringify({ query, variables }),
+		headers: { "Content-Type": "application/json", "X-Chatter-Entity-Encoding": "false" },
+	});
+}