@genn-inc/cluebase-cli 0.0.1

package/src/setup-check-scan-a.mjs

@@ -0,0 +1,849 @@
+// setup-check source/dependency scan helpers (part 1). Extracted for
+// file-size limits; content is unchanged.
+
+import { access, readFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import {
+  extractExecutableModuleStatements,
+  findLifecycleCallApiNames,
+  stripSourceNoise,
+} from "./lifecycle-guard.mjs";
+import {
+  listAllowedSourceFiles,
+} from "./path-policy.mjs";
+import {
+  SETUP_STEP_COMMANDS,
+  SETUP_STEP_SKILLS,
+  SETUP_COMMAND_ROOT_PARTS,
+  SETUP_CODEX_SKILL_ROOT_PARTS,
+  SOURCE_EXTENSIONS,
+  REQUIRED_LIFECYCLE_APIS,
+	REQUIRED_SETUP_DOCUMENT_IDS,
+	FRONTEND_SDK_PACKAGE,
+	DEPENDENCY_FILE_CANDIDATES,
+} from "./setup-check-constants.mjs";
+
+export const exists = async (path) => {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+export const readSetupManifest = async (repoRoot) => {
+	const manifestPath = join(repoRoot, ".cluebase", "setup-manifest.json");
+	if (!(await exists(manifestPath))) return undefined;
+	try {
+		return JSON.parse(await readFile(manifestPath, "utf8"));
+	} catch {
+		return undefined;
+	}
+};
+
+export const validateSetupManifestContract = (manifest) => {
+	if (!manifest || typeof manifest !== "object") {
+		return {
+			checked: false,
+			findings: ["setup manifest is missing or unreadable"],
+		};
+	}
+	const findings = [];
+	if (
+		manifest.cli_invocation?.ai_help_command !==
+		"npx -y @genn-inc/cluebase-cli help --json"
+	) {
+		findings.push("cli_invocation.ai_help_command is missing or outdated");
+	}
+	if (manifest.lifecycle_verification?.owner !== "user") {
+		findings.push("lifecycle_verification.owner must be user");
+	}
+	if (
+		!String(manifest.lifecycle_verification?.rule ?? "").includes(
+			"verify the resulting Cluebase logs",
+		)
+	) {
+		findings.push(
+			"lifecycle_verification.rule must require Cluebase log verification",
+		);
+	}
+	if (
+		!Array.isArray(manifest.ai_owned_workstreams) ||
+		manifest.ai_owned_workstreams.length !== 1 ||
+		manifest.ai_owned_workstreams[0] !== "sdk_lifecycle_placement"
+	) {
+		findings.push("ai_owned_workstreams must be sdk_lifecycle_placement only");
+	}
+	const lifecycleApis = manifest.ai_implementation_scope?.lifecycle_apis;
+	if (
+		!Array.isArray(lifecycleApis) ||
+		lifecycleApis.length !== REQUIRED_LIFECYCLE_APIS.length ||
+		!REQUIRED_LIFECYCLE_APIS.every((apiName) => lifecycleApis.includes(apiName))
+	) {
+		findings.push(
+			"ai_implementation_scope.lifecycle_apis must contain only cluebase.init, cluebase.identify, cluebase.group, and cluebase.reset",
+		);
+	}
+	if (
+		!Array.isArray(manifest.ai_implementation_scope?.out_of_scope_by_default) ||
+		!manifest.ai_implementation_scope.out_of_scope_by_default.includes(
+			"cluebase.track",
+		)
+	) {
+		findings.push("ai_implementation_scope must mark cluebase.track out of scope");
+	}
+	const documentation = manifest.documentation;
+	if (!documentation || typeof documentation !== "object") {
+		findings.push("documentation contract is missing");
+	} else {
+		if (!String(documentation.documents_url ?? "").trim()) {
+			findings.push("documentation.documents_url is missing");
+		}
+		const requiredDocIds = Array.isArray(documentation.required_doc_ids)
+			? documentation.required_doc_ids
+			: [];
+		for (const docId of REQUIRED_SETUP_DOCUMENT_IDS) {
+			if (!requiredDocIds.includes(docId)) {
+				findings.push(`documentation.required_doc_ids is missing ${docId}`);
+			}
+		}
+		if (
+			!documentation.framework_doc_ids_by_framework ||
+			typeof documentation.framework_doc_ids_by_framework !== "object"
+		) {
+			findings.push("documentation.framework_doc_ids_by_framework is missing");
+		}
+		if (!Array.isArray(documentation.selected_framework_doc_ids)) {
+			findings.push("documentation.selected_framework_doc_ids is missing");
+		}
+		if (
+			!Array.isArray(documentation.report_required_fields) ||
+			!documentation.report_required_fields.includes("consulted_document_ids")
+		) {
+			findings.push(
+				"documentation.report_required_fields must include consulted_document_ids",
+			);
+		}
+	}
+	const localEventDelivery = Array.isArray(manifest.required_final_verification)
+		? manifest.required_final_verification.find(
+				(entry) => entry?.id === "local_event_delivery",
+			)
+		: null;
+	if (
+		localEventDelivery?.command !==
+		"user runs the local customer frontend/backend, performs the real product flow, and checks Cluebase setup logs or published batch evidence"
+	) {
+		findings.push(
+			"required_final_verification.local_event_delivery must be user-operated",
+		);
+	}
+	if (
+		!String(localEventDelivery?.completion_meaning ?? "").includes(
+			"user_verification_pending",
+		)
+	) {
+		findings.push(
+			"required_final_verification.local_event_delivery must report user_verification_pending without user evidence",
+		);
+	}
+	const detectedServices = Array.isArray(manifest.detected_services)
+		? manifest.detected_services
+		: [];
+	if (detectedServices.length === 0) {
+		findings.push("detected_services must not be empty");
+	}
+	const hasNextFrontend = detectedServices.some(
+		(target) => target?.kind === "frontend" && target?.framework === "nextjs",
+	);
+	const frontendRuntime = Array.isArray(
+		manifest.required_env_scopes?.frontend_runtime,
+	)
+		? manifest.required_env_scopes.frontend_runtime
+		: [];
+	const _backendRuntime = Array.isArray(
+		manifest.required_env_scopes?.backend_runtime,
+	)
+		? manifest.required_env_scopes.backend_runtime
+		: [];
+	if (
+		(hasNextFrontend ||
+			frontendRuntime.some((name) =>
+				String(name).startsWith("NEXT_PUBLIC_CLUEBASE_"),
+			)) &&
+		!["NEXT_PUBLIC_CLUEBASE_PROJECT_KEY", "NEXT_PUBLIC_CLUEBASE_API_BASE_URL"].every(
+			(name) => frontendRuntime.includes(name),
+		)
+	) {
+		findings.push(
+			"Next.js frontend runtime env must use NEXT_PUBLIC_CLUEBASE_* names",
+		);
+	}
+	return {
+		checked: true,
+		findings,
+	};
+};
+
+export const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export const validateSetupStepFiles = async ({ repoRoot }) => {
+	const missing = [];
+	for (const file of SETUP_STEP_COMMANDS) {
+		const commandPath = join(repoRoot, ...SETUP_COMMAND_ROOT_PARTS, file);
+		if (!(await exists(commandPath))) {
+			missing.push(join(...SETUP_COMMAND_ROOT_PARTS, file));
+		}
+	}
+	for (const skill of SETUP_STEP_SKILLS) {
+		const skillPath = join(
+			repoRoot,
+			...SETUP_CODEX_SKILL_ROOT_PARTS,
+			skill,
+			"SKILL.md",
+		);
+		if (!(await exists(skillPath))) {
+			missing.push(join(...SETUP_CODEX_SKILL_ROOT_PARTS, skill, "SKILL.md"));
+		}
+	}
+	return missing;
+};
+
+export const addCheck = (checks, id, passed, summary, details = {}) => {
+	checks.push({ id, passed, summary, ...details });
+};
+
+export const readAllowedSourceText = async ({
+	repoRoot,
+	allowedSourcePaths,
+	excludedSourcePaths,
+}) => {
+	const files = await listAllowedSourceFiles({
+		repoRoot,
+		allowedSourcePaths,
+		excludedSourcePaths,
+		extensions: SOURCE_EXTENSIONS,
+	});
+	const sources = [];
+	for (const absolutePath of [...new Set(files)]) {
+		sources.push({
+			file_path: relative(resolve(repoRoot), absolutePath),
+			text: await readFile(absolutePath, "utf8"),
+		});
+	}
+	return sources;
+};
+
+export const readDependencyText = async ({ repoRoot, roots }) => {
+	const expandedRoots = roots.flatMap((root) =>
+		root.endsWith("/src") || root.endsWith("/app")
+			? [root, dirname(root)]
+			: [root],
+	);
+	const candidatePaths = [
+		...DEPENDENCY_FILE_CANDIDATES,
+		...expandedRoots.flatMap((root) =>
+			DEPENDENCY_FILE_CANDIDATES.map((file) => join(root, file)),
+		),
+	];
+	const sources = [];
+	for (const path of [...new Set(candidatePaths)]) {
+		const absolutePath = join(repoRoot, path);
+		if (!(await exists(absolutePath))) continue;
+		sources.push({
+			file_path: path,
+			text: await readFile(absolutePath, "utf8"),
+		});
+	}
+	return sources;
+};
+
+export const FRONTEND_ENV_FILE_CANDIDATES = [
+	".env",
+	".env.local",
+	".env.development",
+	".env.development.local",
+	".env.production",
+	".env.production.local",
+	".env.test",
+	".env.test.local",
+];
+
+export const readFrontendConfigText = async ({ repoRoot, roots }) => {
+	const expandedRoots = roots.flatMap((root) =>
+		root.endsWith("/src") || root.endsWith("/app") ? [dirname(root)] : [root],
+	);
+	const sources = [];
+	for (const root of [...new Set(expandedRoots)]) {
+		for (const fileName of FRONTEND_ENV_FILE_CANDIDATES) {
+			const filePath = join(root, fileName);
+			const absolutePath = join(repoRoot, filePath);
+			if (!(await exists(absolutePath))) continue;
+			sources.push({
+				file_path: filePath,
+				text: await readFile(absolutePath, "utf8"),
+			});
+		}
+	}
+	return sources;
+};
+
+export const setupSourcePaths = async ({
+	repoRoot,
+	request,
+	includeFrontend,
+	setupManifest,
+}) => {
+	const requested = request?.allowed_source_paths?.length
+		? request.allowed_source_paths
+		: ["."];
+	if (!includeFrontend) return requested;
+	const detectedServiceRoots = Array.isArray(setupManifest?.detected_services)
+		? setupManifest.detected_services
+				.map((target) => target?.root_path)
+				.filter((root) => typeof root === "string" && root.trim())
+		: [];
+	const candidates = [
+		...requested,
+		...detectedServiceRoots,
+		...detectedServiceRoots.flatMap((root) => [
+			join(root, "src"),
+			join(root, "app"),
+		]),
+		"frontend/src",
+		"src",
+		"app",
+		"apps/admin/src",
+		"apps/visitor/src",
+		"apps/web/src",
+		"apps/frontend/src",
+		"apps/client/src",
+		"packages/frontend",
+	];
+	const existing = [];
+	for (const candidate of [...new Set(candidates)]) {
+		if (await exists(join(repoRoot, candidate))) {
+			existing.push(candidate);
+		}
+	}
+	return existing.length ? existing : requested;
+};
+
+export const setupBackendRootPaths = (request) => {
+	const configuredRoots = [
+		...(Array.isArray(request?.backend_root_paths)
+			? request.backend_root_paths
+			: []),
+		request?.backend_root_path,
+	]
+		.filter((root) => typeof root === "string" && root.trim())
+		.map((root) => root.trim());
+	return configuredRoots.length
+		? [...new Set(configuredRoots)]
+		: (request?.allowed_source_paths ?? []);
+};
+
+export const secretLeakPatterns = [
+	/\bcluebase_(?:[A-Za-z0-9]{32,}|(?:live|test)_[A-Za-z0-9_-]{16,})\b/,
+	/pk_(live|test)_[A-Za-z0-9_-]+/,
+	/sk_(live|test)_[A-Za-z0-9_-]+/,
+	/\bsk-proj-[A-Za-z0-9_-]{20,}\b/,
+	/\bsk-ant-[A-Za-z0-9_-]{20,}\b/,
+	/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b/,
+	/\bgithub_pat_[A-Za-z0-9_]{20,}\b/,
+	/npm_[A-Za-z0-9]{20,}/,
+];
+export const PUBLIC_CLUEBASE_SECRET_ENV_LINE_PATTERN =
+	/^\s*(?:NEXT_PUBLIC|VITE|PUBLIC|NUXT_PUBLIC|REACT_APP)_CLUEBASE_(?:API_KEY|AI_PROVIDER_API_KEY)\s*=/m;
+
+export const findSecretLeaks = (sources) =>
+	sources.flatMap((source) =>
+		secretLeakPatterns.some((pattern) => pattern.test(source.text)) ||
+		PUBLIC_CLUEBASE_SECRET_ENV_LINE_PATTERN.test(source.text)
+			? [source.file_path]
+			: [],
+	);
+
+export const startsWithRoot = (filePath, root) =>
+	filePath === root || filePath.startsWith(`${root.replace(/\/+$/, "")}/`);
+
+export const packageJsonDependencyNames = (text) => {
+	try {
+		const parsed = JSON.parse(text);
+		return [
+			"dependencies",
+			"devDependencies",
+			"optionalDependencies",
+			"peerDependencies",
+		].flatMap((field) =>
+			parsed && typeof parsed[field] === "object" && parsed[field] !== null
+				? Object.keys(parsed[field])
+				: [],
+		);
+	} catch {
+		return [];
+	}
+};
+
+export const packageJsonDependencies = (text) => {
+	try {
+		const parsed = JSON.parse(text);
+		return [
+			"dependencies",
+			"devDependencies",
+			"optionalDependencies",
+			"peerDependencies",
+		].reduce((result, field) => {
+			if (
+				parsed &&
+				typeof parsed[field] === "object" &&
+				parsed[field] !== null
+			) {
+				for (const [name, version] of Object.entries(parsed[field])) {
+					if (typeof version === "string") {
+						result.set(name, version);
+					}
+				}
+			}
+			return result;
+		}, new Map());
+	} catch {
+		return new Map();
+	}
+};
+
+export const packageJsonHasDependency = (text, packageName) =>
+	packageJsonDependencies(text).has(packageName);
+
+export const packageJsonDependencyVersion = (text, packageName) =>
+	packageJsonDependencies(text).get(packageName) ?? null;
+
+export const packageJsonSourcesWithDependency = (dependencySources, packageName) =>
+	dependencySources.filter(
+		(source) =>
+			source.file_path.endsWith("package.json") &&
+			packageJsonHasDependency(source.text, packageName),
+	);
+
+export const nextPackageRoots = (dependencySources) =>
+	packageJsonSourcesWithDependency(dependencySources, "next").map((source) =>
+		dirname(source.file_path),
+	);
+
+export const frontendPackageRoots = (dependencySources) =>
+	dependencySources
+		.filter((source) => {
+			if (!source.file_path.endsWith("package.json")) return false;
+			const dependencies = new Set(packageJsonDependencyNames(source.text));
+			return [
+				FRONTEND_SDK_PACKAGE,
+				"next",
+				"vite",
+				"react",
+				"vue",
+				"@angular/core",
+			].some((packageName) => dependencies.has(packageName));
+		})
+		.map((source) => dirname(source.file_path));
+
+export const sourceIsUnderAnyRoot = (source, roots) =>
+	roots.some((root) => {
+		const normalizedRoot = root.replace(/\/+$/, "");
+		return (
+			normalizedRoot === "." ||
+			normalizedRoot === "" ||
+			startsWithRoot(source.file_path, normalizedRoot)
+		);
+	});
+
+export const sourceIsUnderFrontendRoot = (source, roots) => {
+	const normalizedPath = source.file_path.replaceAll("\\", "/");
+	if (
+		/(?:^|\/)(?:frontend|apps\/(?:admin|visitor|web|frontend|client)|packages\/frontend)(?:\/|$)/.test(
+			normalizedPath,
+		)
+	) {
+		return true;
+	}
+	if (sourceImportsFrontendSdk(source)) return true;
+	return roots.some((root) => {
+		const normalizedRoot = root.replace(/\/+$/, "");
+		if (normalizedRoot === "." || normalizedRoot === "") {
+			return /^(?:src|app)\//.test(normalizedPath);
+		}
+		return startsWithRoot(normalizedPath, normalizedRoot);
+	});
+};
+
+export const hasUseClientDirective = (text) =>
+	/^\s*(?:"use client"|'use client')\s*;?/.test(text);
+
+export const dependencySourceHasPackage = (source, packageName) => {
+	if (source.file_path.endsWith("package.json")) {
+		return packageJsonDependencyNames(source.text).includes(packageName);
+	}
+	const packagePattern = new RegExp(
+		`(^|[\\s"'=,{\\[]+)${escapeRegex(packageName)}($|[\\s"'=<>~!,}\\]]+)`,
+		"i",
+	);
+	return source.text
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => line && !line.startsWith("#"))
+		.some((line) => packagePattern.test(line));
+};
+
+export const dependencyHasAnyPackage = (dependencySources, packageNames) =>
+	dependencySources.some((source) =>
+		packageNames.some((packageName) =>
+			dependencySourceHasPackage(source, packageName),
+		),
+	);
+
+export const sourceHasPythonImport = (source, importName) => {
+	const importPattern = new RegExp(
+		`(^|\\n)\\s*(?:from\\s+${escapeRegex(importName)}\\b|import\\s+${escapeRegex(importName)}\\b)`,
+	);
+	return importPattern.test(
+		stripSourceNoise(source.text, { stripStrings: true }),
+	);
+};
+
+export const sourcesHavePythonImport = (sources, importNames) =>
+	sources.some((source) =>
+		importNames.some((importName) => sourceHasPythonImport(source, importName)),
+	);
+
+export const sourceHasNodeImport = (source, importName) => {
+	const importPattern = new RegExp(
+		`(?:from\\s*["']${escapeRegex(importName)}(?:/[^"']*)?["']|` +
+			`import\\s*["']${escapeRegex(importName)}(?:/[^"']*)?["']|` +
+			`require\\(\\s*["']${escapeRegex(importName)}(?:/[^"']*)?["']\\s*\\))`,
+	);
+	return extractExecutableModuleStatements(source.text).some((statement) =>
+		importPattern.test(statement),
+	);
+};
+
+export const sourcesHaveNodeImport = (sources, importNames) =>
+	sources.some((source) =>
+		importNames.some((importName) => sourceHasNodeImport(source, importName)),
+	);
+
+export const sourcesHaveBackendSdkImport = (sources, spec) =>
+	spec.language === "node"
+		? sourcesHaveNodeImport(sources, spec.imports)
+		: sourcesHavePythonImport(sources, spec.imports);
+
+export const sourcesHaveFrontendSdkImport = (sources) =>
+	sources.some((source) => sourceImportsFrontendSdk(source));
+
+export const sourceImportsFrontendSdk = (source) =>
+	sourceTextImportsFrontendSdk(source.text);
+
+export const sourceTextImportsFrontendSdk = (text) =>
+	extractExecutableModuleStatements(text).some((statement) =>
+		new RegExp(
+			`(?:from\\s*["']${escapeRegex(FRONTEND_SDK_PACKAGE)}["']|import\\s*["']${escapeRegex(FRONTEND_SDK_PACKAGE)}["'])`,
+		).test(statement),
+	);
+
+export const parseNamedSpecifiers = (specifiers) =>
+	specifiers
+		.split(",")
+		.map((specifier) => specifier.trim())
+		.filter(Boolean)
+		.map((specifier) => {
+			const match = /^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/.exec(
+				specifier,
+			);
+			if (!match) return null;
+			return {
+				imported: match[1],
+				local: match[2] ?? match[1],
+				exported: match[2] ?? match[1],
+			};
+		})
+		.filter(Boolean);
+
+export const sourceDirectlyProvidesApiFromFrontendSdk = (text, apiName) => {
+	const statements = extractExecutableModuleStatements(text);
+	const statementsJoined = statements.join("\n");
+	// Default-export 形式: `import cluebase from "@genn-inc/cluebase-frontend-sdk"` + `cluebase.identify(...)`
+	// apiName が namespace 形式 (= "cluebase.X") なら、 default import の local 名と prefix を比較し、
+	// 当該 method の呼出が source text 全体に存在するかを確認。
+	if (apiName.includes(".")) {
+		const [prefix, method] = apiName.split(".");
+		const defaultImportPattern = new RegExp(
+			`import\\s+([A-Za-z_$][\\w$]*)\\s+from\\s*["']${escapeRegex(FRONTEND_SDK_PACKAGE)}["']`,
+		);
+		const defaultImportMatch = statementsJoined.match(defaultImportPattern);
+		if (defaultImportMatch) {
+			const local = defaultImportMatch[1];
+			if (local === prefix) {
+				// 呼出 detection は source 全体 text に対して行う (= import/export 抽出ではなく)
+				const sourceClean = stripSourceNoise(text, { stripStrings: true });
+				const callPattern = new RegExp(
+					`\\b${escapeRegex(local)}\\.${escapeRegex(method)}\\s*\\(`,
+				);
+				if (callPattern.test(sourceClean)) {
+					return true;
+				}
+			}
+		}
+	}
+	return false;
+};
+
+export const frontendSdkNamespaces = (text) =>
+	[
+		...extractExecutableModuleStatements(text)
+			.join("\n")
+			.matchAll(
+				/import\s*\*\s*as\s*([A-Za-z_$][\w$]*)\s*from\s*["']([^"']+)["']/g,
+			),
+	]
+		.filter((match) => match[2] === FRONTEND_SDK_PACKAGE)
+		.map((match) => match[1]);
+
+export const sourceForwardsFrontendSdkApi = (source, apiName) => {
+	const text = source.text;
+	if (sourceDirectlyProvidesApiFromFrontendSdk(text, apiName)) return true;
+	return frontendSdkNamespaces(text).some((namespaceName) =>
+		new RegExp(
+			`export\\s+const\\s+${escapeRegex(apiName)}\\s*=\\s*${escapeRegex(namespaceName)}\\.${escapeRegex(apiName)}\\b`,
+		).test(text),
+	);
+};
+
+export const localImportSpecifiersForApi = (text, apiName) =>
+	[
+		...extractExecutableModuleStatements(text)
+			.join("\n")
+			.matchAll(/import\s*{([^}]+)}\s*from\s*["']([^"']+)["']/g),
+	]
+		.filter((match) => match[2].startsWith(".") || match[2].startsWith("@/"))
+		.flatMap((match) =>
+			parseNamedSpecifiers(match[1])
+				.filter(
+					(specifier) =>
+						specifier.imported === apiName && specifier.local === apiName,
+				)
+				.map(() => match[2]),
+		);
+
+export const importSpecifiers = (text) =>
+	[
+		...extractExecutableModuleStatements(text)
+			.join("\n")
+			.matchAll(/import\s+(?:[\s\S]*?\s+from\s+)?["']([^"']+)["']/g),
+	]
+		.map((match) => match[1] ?? match[2])
+		.filter(Boolean);
+
+export const candidateSourcePaths = (basePath) => [
+	basePath,
+	...SOURCE_EXTENSIONS.map((extension) => `${basePath}${extension}`),
+	...SOURCE_EXTENSIONS.map((extension) => join(basePath, `index${extension}`)),
+];
+
+export const resolveLocalSource = ({ importerPath, sourceByPath, specifier }) => {
+	const candidates = [];
+	if (specifier.startsWith(".")) {
+		candidates.push(
+			...candidateSourcePaths(join(dirname(importerPath), specifier)),
+		);
+	}
+	if (specifier.startsWith("@/")) {
+		const srcIndex = importerPath.lastIndexOf("/src/");
+		if (srcIndex >= 0) {
+			candidates.push(
+				...candidateSourcePaths(
+					join(
+						importerPath.slice(0, srcIndex + "/src".length),
+						specifier.slice(2),
+					),
+				),
+			);
+		}
+		for (const root of [
+			"src",
+			"frontend/src",
+			"apps/web/src",
+			"apps/admin/src",
+			"apps/visitor/src",
+		]) {
+			candidates.push(...candidateSourcePaths(join(root, specifier.slice(2))));
+		}
+	}
+	return candidates
+		.map((candidate) => sourceByPath.get(candidate))
+		.find(Boolean);
+};
+
+// Default import of `localName` from a LOCAL module (relative or `@/`).
+// Returns the module specifier when found, else null. Used to trace an
+// adapter singleton such as `import cluebase from "@/lib/cluebase"`.
+export const localDefaultImportModule = (text, localName) => {
+	const statements = extractExecutableModuleStatements(text).join("\n");
+	const match = statements.match(
+		new RegExp(
+			`import\\s+${escapeRegex(localName)}\\s+from\\s*["']([^"']+)["']`,
+		),
+	);
+	if (!match) return null;
+	const specifier = match[1];
+	return specifier.startsWith(".") || specifier.startsWith("@/")
+		? specifier
+		: null;
+};
+
+// A local adapter module re-exports the frontend SDK default instance when it
+// imports the SDK default and re-exports that same binding
+// (`import cluebase from "@genn-inc/cluebase-frontend-sdk"; ...; export default cluebase;`).
+// This is the prescribed `src/lib/cluebase.ts` singleton, so calls made through it
+// are genuinely wired to the frontend SDK.
+export const sourceReExportsFrontendSdkDefault = (text) => {
+	const joined = extractExecutableModuleStatements(text).join("\n");
+	const importMatch = joined.match(
+		new RegExp(
+			`import\\s+([A-Za-z_$][\\w$]*)\\s+from\\s*["']${escapeRegex(
+				FRONTEND_SDK_PACKAGE,
+			)}["']`,
+		),
+	);
+	if (!importMatch) return false;
+	const sdkLocal = importMatch[1];
+	return new RegExp(`export\\s+default\\s+${escapeRegex(sdkLocal)}\\b`).test(
+		joined,
+	);
+};
+
+export const sourceHasVerifiedFrontendSdkAccess = ({
+	apiNames,
+	source,
+	sourceByPath,
+}) =>
+	apiNames.every((apiName) => {
+		if (sourceDirectlyProvidesApiFromFrontendSdk(source.text, apiName)) {
+			return true;
+		}
+		if (
+			localImportSpecifiersForApi(source.text, apiName).some((specifier) => {
+				const importedSource = resolveLocalSource({
+					importerPath: source.file_path,
+					sourceByPath,
+					specifier,
+				});
+				return importedSource
+					? sourceForwardsFrontendSdkApi(importedSource, apiName)
+					: false;
+			})
+		) {
+			return true;
+		}
+		// Adapter default re-export: the lifecycle file calls `cluebase.<method>()`
+		// where `cluebase` is default-imported from a local adapter that re-exports
+		// the frontend SDK default instance. This is the prescribed
+		// `src/lib/cluebase.ts` singleton imported from UI hooks, so it counts as
+		// verified SDK wiring.
+		if (apiName.includes(".")) {
+			const [prefix] = apiName.split(".");
+			const adapterModule = localDefaultImportModule(source.text, prefix);
+			if (adapterModule) {
+				const importedSource = resolveLocalSource({
+					importerPath: source.file_path,
+					sourceByPath,
+					specifier: adapterModule,
+				});
+				if (
+					importedSource &&
+					sourceReExportsFrontendSdkDefault(importedSource.text)
+				) {
+					return true;
+				}
+			}
+		}
+		return false;
+	});
+
+export const NEXT_PUBLIC_CLUEBASE_NAMES = ["CLUEBASE_PROJECT_KEY", "CLUEBASE_API_BASE_URL"];
+export const processEnvAccessSource = (name) =>
+	`process\\.env(?:\\.${escapeRegex(name)}\\b|\\[\\s*["']${escapeRegex(
+		name,
+	)}["']\\s*\\])`;
+export const processEnvAccessPattern = (name) =>
+	new RegExp(`\\b${processEnvAccessSource(name)}`);
+export const processEnvDestructuringPattern = (name) =>
+	new RegExp(
+		`\\b(?:const|let|var)\\s*\\{[\\s\\S]{0,800}\\b${escapeRegex(
+			name,
+		)}\\b(?:\\s*:)?[\\s\\S]{0,800}\\}\\s*=\\s*process\\.env\\b`,
+	);
+export const sourceReadsProcessEnvName = (text, name) =>
+	processEnvAccessPattern(name).test(text) ||
+	processEnvDestructuringPattern(name).test(text);
+export const PUBLIC_CLUEBASE_SECRET_ENV_PATTERN =
+	/\b(?:process\.env(?:\.(?:(?:NEXT_PUBLIC|VITE|PUBLIC|NUXT_PUBLIC|REACT_APP)_CLUEBASE_(?:API_KEY|AI_PROVIDER_API_KEY))\b|\[\s*["'](?:(?:NEXT_PUBLIC|VITE|PUBLIC|NUXT_PUBLIC|REACT_APP)_CLUEBASE_(?:API_KEY|AI_PROVIDER_API_KEY))["']\s*\])|(?:const|let|var)\s*\{[\s\S]{0,800}\b(?:NEXT_PUBLIC|VITE|PUBLIC|NUXT_PUBLIC|REACT_APP)_CLUEBASE_(?:API_KEY|AI_PROVIDER_API_KEY)\b[\s\S]{0,800}\}\s*=\s*process\.env\b)/;
+
+export const findFrontendLifecycleNonPublicEnvFiles = ({ frontendSources }) => {
+	return frontendSources
+		.filter(
+			(source) =>
+				sourceImportsFrontendSdk(source) ||
+				findLifecycleCallApiNames(
+					stripSourceNoise(source.text, { stripStrings: true }),
+				).length > 0,
+		)
+		.filter(
+			(source) =>
+				/\bprocess\.env(?:\.CLUEBASE_[A-Z0-9_]+\b|\[\s*["']CLUEBASE_[A-Z0-9_]+["']\s*\])/.test(
+					source.text,
+				) ||
+				/\b(?:const|let|var)\s*\{[\s\S]{0,800}\bCLUEBASE_[A-Z0-9_]+\b[\s\S]{0,800}\}\s*=\s*process\.env\b/.test(
+					source.text,
+				) ||
+				PUBLIC_CLUEBASE_SECRET_ENV_PATTERN.test(source.text) ||
+				NEXT_PUBLIC_CLUEBASE_NAMES.some((name) =>
+					sourceReadsProcessEnvName(source.text, name),
+				),
+		)
+		.map((source) => source.file_path);
+};
+
+export const sourceHasComponentScopedCluebaseInitCall = (text) => {
+	const source = stripSourceNoise(text, { stripStrings: true });
+	return (
+		/\buse(?:Effect|LayoutEffect|InsertionEffect)\s*\([\s\S]{0,1200}\bcluebase\.init\s*\(/.test(
+			source,
+		) ||
+		/\b(?:export\s+)?function\s+[A-Z][\w$]*\s*\([^)]*\)\s*\{[\s\S]{0,1600}\bcluebase\.init\s*\(/.test(
+			source,
+		) ||
+		/\bexport\s+default\s+function(?:\s+[A-Za-z_$][\w$]*)?\s*\([^)]*\)\s*\{[\s\S]{0,1600}\bcluebase\.init\s*\(/.test(
+			source,
+		) ||
+		/\bexport\s+default\s*(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>\s*(?:\{[\s\S]{0,1600}\bcluebase\.init\s*\(|[\s\S]{0,400}\bcluebase\.init\s*\()/.test(
+			source,
+		) ||
+		/\b(?:export\s+)?(?:const|let|var)\s+[A-Z][\w$]*\s*=\s*(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>\s*(?:\{[\s\S]{0,1600}\bcluebase\.init\s*\(|[\s\S]{0,400}\bcluebase\.init\s*\()/.test(
+			source,
+		)
+	);
+};
+
+export const sourceHasAuthCallbackScopedCluebaseInitCall = (text) => {
+	const source = stripSourceNoise(text, { stripStrings: true });
+	return (
+		/\bonSuccess\s*:\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>\s*\{[\s\S]{0,1600}\bcluebase\.init\s*\(/.test(
+			source,
+		) ||
+		/\b(?:login|register|signIn|signUp|handleLogin|handleRegister)\s*(?:=\s*)?(?:async\s*)?(?:function\s*)?\([^)]*\)\s*\{[\s\S]{0,1600}\bcluebase\.init\s*\(/i.test(
+			source,
+		) ||
+		/\.(?:then|finally)\s*\(\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>\s*\{[\s\S]{0,1600}\bcluebase\.init\s*\(/.test(
+			source,
+		)
+	);
+};