@genn-inc/cluebase-cli 0.0.1

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

@@ -0,0 +1,994 @@
+// setup-check lifecycle/find detectors (part 2). Extracted for file-size
+// limits; content is unchanged.
+
+import { dirname, join } from "node:path";
+import {
+  stripSourceNoise,
+} from "./lifecycle-guard.mjs";
+import {
+  escapeRegex,
+  nextPackageRoots,
+  sourceIsUnderAnyRoot,
+  hasUseClientDirective,
+  sourceImportsFrontendSdk,
+} from "./setup-check-scan-a.mjs";
+
+export const findNextLifecycleMissingUseClientFiles = ({
+	dependencySources,
+	frontendSources,
+}) => {
+	const roots = nextPackageRoots(dependencySources);
+	if (roots.length === 0) return [];
+	return frontendSources
+		.filter((source) => sourceIsUnderAnyRoot(source, roots))
+		.filter(
+			(source) =>
+				sourceImportsFrontendSdk(source) ||
+				/\bcluebase\.init\s*\(/.test(
+					stripSourceNoise(source.text, { stripStrings: true }),
+				),
+		)
+		.filter((source) => !hasUseClientDirective(source.text))
+		.map((source) => source.file_path);
+};
+
+export const findCluebaseInitCallEmptyEnvFallbackFiles = (frontendSources) =>
+	frontendSources
+		.filter((source) => sourceImportsFrontendSdk(source))
+		.filter((source) =>
+			/(?:process\.env\.(?:NEXT_PUBLIC_|PUBLIC_|NUXT_PUBLIC_|REACT_APP_)?CLUEBASE_[A-Z0-9_]+|import\.meta\.env\.VITE_CLUEBASE_[A-Z0-9_]+)\s*(?:\?\?|\|\|)\s*(["'])\1/.test(
+				stripSourceNoise(source.text),
+			),
+		)
+		.map((source) => source.file_path);
+
+export const findFrontendInitBeforeCluebaseInitCallFiles = (frontendSources) =>
+	frontendSources
+		.filter((source) => sourceImportsFrontendSdk(source))
+		.filter((source) => {
+			const text = stripSourceNoise(source.text, { stripStrings: true });
+			const initializedIndex = text.search(/\binitialized\s*=\s*true\b/);
+			const cluebaseInitIndex = text.search(/\bcluebase\.init\s*\(/);
+			return (
+				initializedIndex >= 0 &&
+				cluebaseInitIndex >= 0 &&
+				initializedIndex < cluebaseInitIndex
+			);
+		})
+		.map((source) => source.file_path);
+
+export const findFrontendBackendTracePropagationMissingFiles = ({
+	backendPresent,
+	frontendSources,
+}) => {
+	if (!backendPresent) return [];
+	return frontendSources
+		.filter((source) =>
+			/\bcluebase\.init\s*\(/.test(
+				stripSourceNoise(source.text, { stripStrings: true }),
+			),
+		)
+		.filter(
+			(source) =>
+				!/\btracePropagationOrigins\b/.test(
+					stripSourceNoise(source.text, { stripStrings: true }),
+				),
+		)
+		.map((source) => source.file_path);
+};
+
+export const nextRouteApiPathFromFile = (source) => {
+	const normalized = source.file_path.replaceAll("\\", "/");
+	const match = /(?:^|\/)(?:src\/)?app\/(.+)\/route\.(?:ts|tsx|js|jsx)$/.exec(
+		normalized,
+	);
+	if (!match) return null;
+	const routeSegments = match[1]
+		.split("/")
+		.filter((segment) => segment && !/^\(.+\)$/.test(segment));
+	if (routeSegments[0] !== "api") return null;
+	return `/${routeSegments.join("/")}`.replace(/\/+/g, "/").toLowerCase();
+};
+
+export const findBackendSdkInitMissingServiceKeyFiles = ({
+	backendSources,
+	framework,
+}) => {
+	if (framework !== "fastapi") return [];
+	return backendSources
+		.filter((source) =>
+			/\b(?:cluebase\.init|cluebase_init_fastapi)\s*\(/.test(
+				stripSourceNoise(source.text, { stripStrings: true }),
+			),
+		)
+		.filter(
+			(source) =>
+				!/\bcluebase\.init\s*\(\s*\{[\s\S]{0,1600}["']service_key["']\s*:/.test(
+					stripSourceNoise(source.text),
+				) &&
+				!/\bcluebase_init_fastapi\s*\([\s\S]{0,1600}\bservice_key\s*=/.test(
+					stripSourceNoise(source.text),
+				),
+		)
+		.map((source) => source.file_path);
+};
+
+export const findFastapiMissingMiddlewareFiles = ({ backendSources, framework }) => {
+	if (framework !== "fastapi") return [];
+	const combined = backendSources
+		.map((source) => stripSourceNoise(source.text, { stripStrings: true }))
+		.join("\n");
+	if (
+		/\bcluebase_init_fastapi\s*\(/.test(combined) ||
+		/\bCluebaseFastApiMiddleware\b/.test(combined)
+	) {
+		return [];
+	}
+	return backendSources
+		.filter((source) =>
+			/\bFastAPI\s*\(/.test(
+				stripSourceNoise(source.text, { stripStrings: true }),
+			),
+		)
+		.map((source) => source.file_path);
+};
+
+export const findBackendCluebaseEnvRequiredIndexFiles = (backendSources) =>
+	backendSources
+		.filter((source) =>
+			/os\.environ\s*\[\s*["']CLUEBASE_[A-Z0-9_]+["']\s*\]/.test(
+				stripSourceNoise(source.text),
+			),
+		)
+		.map((source) => source.file_path);
+
+export const executableLifecycleCallSnippets = (text) => {
+	const snippets = [];
+	let index = 0;
+	while (index < text.length) {
+		const char = text[index];
+		const next = text[index + 1];
+		if (char === "/" && next === "/") {
+			while (index < text.length && text[index] !== "\n") index += 1;
+			continue;
+		}
+		if (char === "#") {
+			while (index < text.length && text[index] !== "\n") index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			index += 2;
+			while (
+				index < text.length &&
+				!(text[index] === "*" && text[index + 1] === "/")
+			) {
+				index += 1;
+			}
+			index += index < text.length ? 2 : 0;
+			continue;
+		}
+		if (char === "'" || char === '"' || char === "`") {
+			const quote = char;
+			index += 1;
+			while (index < text.length) {
+				if (quote !== "`" && text[index] === "\\") {
+					index += 2;
+					continue;
+				}
+				if (text[index] === quote) {
+					index += 1;
+					break;
+				}
+				index += 1;
+			}
+			continue;
+		}
+		const match = /^(cluebase\.identify|cluebase\.group)\b/.exec(text.slice(index));
+		if (!match || /[A-Za-z0-9_$]/.test(text[index - 1] ?? "")) {
+			index += 1;
+			continue;
+		}
+		let cursor = index + match[1].length;
+		while (/\s/.test(text[cursor] ?? "")) cursor += 1;
+		if (text[cursor] !== "(") {
+			index += 1;
+			continue;
+		}
+		let depth = 0;
+		let end = cursor;
+		while (end < text.length) {
+			const current = text[end];
+			if (current === "'" || current === '"' || current === "`") {
+				const quote = current;
+				end += 1;
+				while (end < text.length) {
+					if (quote !== "`" && text[end] === "\\") {
+						end += 2;
+						continue;
+					}
+					if (text[end] === quote) {
+						end += 1;
+						break;
+					}
+					end += 1;
+				}
+				continue;
+			}
+			if (current === "(") depth += 1;
+			if (current === ")") {
+				depth -= 1;
+				if (depth === 0) {
+					end += 1;
+					break;
+				}
+			}
+			end += 1;
+		}
+		snippets.push(text.slice(index, end));
+		index = end;
+	}
+	return snippets;
+};
+
+export const sourceHasHardcodedLifecycleIdentity = (source) => {
+	const text = stripSourceNoise(source.text);
+	const lifecycleCalls = executableLifecycleCallSnippets(source.text);
+	// cluebase.identify(<arg1>): arg1 が hardcoded string なら NG
+	// cluebase.group(<arg1>, <arg2>): arg1 は groupType literal で OK、 arg2 が hardcoded string なら NG
+	if (
+		lifecycleCalls.some((call) =>
+			/\bcluebase\.identify\s*\(\s*(?:["'][^"']+["']|`[^`$]+`)/.test(call),
+		)
+	) {
+		return true;
+	}
+	if (
+		lifecycleCalls.some((call) =>
+			// cluebase.group の第 2 引数 (= groupKey) が hardcoded string なら NG
+			// 第 1 引数 (= type literal "organization") は spec 通り
+			/\bcluebase\.group\s*\(\s*(?:["'][^"']+["']|`[^`$]+`)\s*,\s*(?:["'][^"']+["']|`[^`$]+`)/.test(
+				call,
+			),
+		)
+	) {
+		return true;
+	}
+	if (
+		lifecycleCalls.some((call) =>
+			/\b(?:cluebase\.identify|cluebase\.group)\s*\(\s*\{[\s\S]{0,500}\b(?:id|userId|user_id|accountId|account_id|workspaceId|workspace_id)\b\s*:\s*(?:["'][^"']+["']|`[^`$]+`)/.test(
+				call,
+			),
+		)
+	) {
+		return true;
+	}
+	const hardcodedIdentifiers = [
+		...text.matchAll(
+			/(?:^|[;\n])\s*(?:(?:const|let|var)\s+)?([A-Za-z_$][\w$]*)\s*(?::[^=\n]+)?=\s*(?:["'][^"']+["']|`[^`$]+`)/g,
+		),
+	].map((match) => match[1]);
+	if (
+		hardcodedIdentifiers.some((name) =>
+			lifecycleCalls.some((call) =>
+				// identify は第 1 引数、 group は第 2 引数 (= groupKey) が対象
+				new RegExp(
+					`\\b(?:cluebase\\.identify\\s*\\(\\s*${name}\\b|cluebase\\.group\\s*\\(\\s*(?:["'][^"']+["']|\`[^\`$]+\`)\\s*,\\s*${name}\\b)`,
+				).test(call),
+			),
+		)
+	) {
+		return true;
+	}
+	const hardcodedObjectNames = [
+		...text.matchAll(
+			/(?:^|[;\n])\s*(?:(?:const|let|var)\s+)?([A-Za-z_$][\w$]*)\s*(?::[^=\n]+)?=\s*\{[\s\S]{0,800}:\s*["'][^"']+["'][\s\S]{0,800}\}/g,
+		),
+	].map((match) => match[1]);
+	return hardcodedObjectNames.some((name) =>
+		lifecycleCalls.some((call) =>
+			new RegExp(
+				`\\b(?:cluebase\\.identify\\s*\\(\\s*${name}\\s*(?:\\.|\\[)|cluebase\\.group\\s*\\(\\s*(?:["'][^"']+["']|\`[^\`$]+\`)\\s*,\\s*${name}\\s*(?:\\.|\\[))`,
+			).test(call),
+		),
+	);
+};
+
+export const findHardcodedLifecycleIdentityFiles = (sources) =>
+	sources
+		.filter(sourceHasHardcodedLifecycleIdentity)
+		.map((source) => source.file_path);
+
+export const READ_SIDE_EFFECT_LIFECYCLE_PATTERN =
+	/\b(?:cluebase\.init|cluebase\.identify|cluebase\.group|cluebase\.reset)\s*\(/;
+
+export const frontendQueryFunctionBlocks = (text) => {
+	const stripped = stripSourceNoise(text, { stripStrings: true });
+	const lines = stripped.split(/\r?\n/);
+	const blocks = [];
+	for (const match of stripped.matchAll(
+		/\b(?:useQuery|useSuspenseQuery|useInfiniteQuery|queryOptions)\s*\(/g,
+	)) {
+		blocks.push(
+			balancedBlockFrom({
+				close: ")",
+				open: "(",
+				startIndex: match.index,
+				text: stripped,
+			}),
+		);
+	}
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (!/\bqueryFn\b/.test(line)) continue;
+		const block = [line];
+		if (line.includes("{")) {
+			for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+				block.push(lines[cursor]);
+				if (/^\s*}\s*,?\s*$/.test(lines[cursor])) break;
+			}
+		}
+		blocks.push(block.join("\n"));
+	}
+	for (const match of stripped.matchAll(
+		/\bqueryFn\s*(?::\s*([A-Za-z_$][\w$]*)\b)?/g,
+	)) {
+		const name = match[1] ?? "queryFn";
+		const declaration = new RegExp(
+			`(?:(?:export\\s+)?function\\s+${escapeRegex(name)}\\s*\\([^)]*\\)|(?:export\\s+)?(?:const|let|var)\\s+${escapeRegex(name)}\\s*=\\s*(?:async\\s*)?(?:\\([^)]*\\)|[A-Za-z_$][\\w$]*)\\s*=>)[\\s\\S]{0,1600}`,
+			"g",
+		);
+		blocks.push(
+			...[...stripped.matchAll(declaration)].map((entry) => entry[0]),
+		);
+	}
+	return blocks;
+};
+
+export const frontendLifecycleExportedFunctionNames = (source) => {
+	const stripped = stripSourceNoise(source.text, { stripStrings: true });
+	const names = [];
+	const declarations = [
+		...stripped.matchAll(
+			/\bexport\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*\{[\s\S]{0,1600}/g,
+		),
+		...stripped.matchAll(
+			/\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>[\s\S]{0,1600}/g,
+		),
+	];
+	for (const declaration of declarations) {
+		if (READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(declaration[0])) {
+			names.push(declaration[1]);
+		}
+	}
+	return names;
+};
+
+export const sourceHasDefaultLifecycleExport = (source) => {
+	const stripped = stripSourceNoise(source.text, { stripStrings: true });
+	for (const match of stripped.matchAll(
+		/\bexport\s+default\s+(?:async\s+)?function\b[^{]*\{/g,
+	)) {
+		if (
+			READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(
+				balancedBlockFrom({
+					close: "}",
+					open: "{",
+					startIndex: match.index,
+					text: stripped,
+				}),
+			)
+		) {
+			return true;
+		}
+	}
+	for (const match of stripped.matchAll(
+		/\bexport\s+default\s+(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>\s*\{/g,
+	)) {
+		if (
+			READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(
+				balancedBlockFrom({
+					close: "}",
+					open: "{",
+					startIndex: match.index,
+					text: stripped,
+				}),
+			)
+		) {
+			return true;
+		}
+	}
+	for (const match of stripped.matchAll(
+		/\bexport\s+default\s+([A-Za-z_$][\w$]*)\b/g,
+	)) {
+		const name = match[1];
+		const declaration = new RegExp(
+			`(?:(?:export\\s+)?function\\s+${escapeRegex(name)}\\s*\\([^)]*\\)\\s*\\{|(?:export\\s+)?(?:const|let|var)\\s+${escapeRegex(name)}\\s*=\\s*(?:async\\s*)?(?:\\([^)]*\\)|[A-Za-z_$][\\w$]*)\\s*=>\\s*\\{)`,
+			"g",
+		);
+		for (const declarationMatch of stripped.matchAll(declaration)) {
+			if (
+				READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(
+					balancedBlockFrom({
+						close: "}",
+						open: "{",
+						startIndex: declarationMatch.index,
+						text: stripped,
+					}),
+				)
+			) {
+				return true;
+			}
+		}
+	}
+	return false;
+};
+
+export const frontendImportCandidates = ({ importerPath, specifier }) => {
+	let base = null;
+	if (specifier.startsWith(".")) {
+		base = join(
+			dirname(importerPath),
+			specifier.startsWith("./") || specifier.startsWith("../")
+				? specifier
+				: specifier.replace(/^\.+/, ""),
+		).replaceAll("\\", "/");
+	} else if (specifier.startsWith("@/") || specifier.startsWith("~/")) {
+		const pathParts = importerPath.replaceAll("\\", "/").split("/");
+		const srcIndex = pathParts.lastIndexOf("src");
+		const aliasBase =
+			srcIndex >= 0
+				? pathParts.slice(0, srcIndex + 1).join("/")
+				: pathParts.slice(0, 1).join("/");
+		base = join(aliasBase, specifier.slice(2)).replaceAll("\\", "/");
+	}
+	if (!base) return [];
+	return [
+		base,
+		`${base}.ts`,
+		`${base}.tsx`,
+		`${base}.js`,
+		`${base}.jsx`,
+		join(base, "index.ts").replaceAll("\\", "/"),
+		join(base, "index.tsx").replaceAll("\\", "/"),
+		join(base, "index.js").replaceAll("\\", "/"),
+		join(base, "index.jsx").replaceAll("\\", "/"),
+	];
+};
+
+export const frontendQueryFnLifecycleAliasNames = ({
+	frontendSources,
+	querySource,
+}) => {
+	const sourceByPath = new Map(
+		frontendSources.map((source) => [source.file_path, source]),
+	);
+	const aliases = new Set();
+	const text = stripSourceNoise(querySource.text);
+	for (const match of text.matchAll(
+		/\bimport\s+([^;]+?)\s+from\s+["']([^"']+)["']/g,
+	)) {
+		const clause = match[1].trim();
+		const importedSource = frontendImportCandidates({
+			importerPath: querySource.file_path,
+			specifier: match[2],
+		})
+			.map((candidate) => sourceByPath.get(candidate))
+			.find(Boolean);
+		if (!importedSource) continue;
+		const exportedLifecycleNames = new Set(
+			frontendLifecycleExportedFunctionNames(importedSource),
+		);
+		const namedImport = /\{([\s\S]*)\}/.exec(clause);
+		if (namedImport) {
+			for (const rawPart of namedImport[1].split(",")) {
+				const part = rawPart.trim();
+				if (!part) continue;
+				const [exported, local = exported] = part
+					.split(/\s+as\s+/i)
+					.map((entry) => entry.trim());
+				if (exportedLifecycleNames.has(exported)) {
+					aliases.add(local);
+				}
+			}
+		}
+		const defaultImport = clause
+			.replace(/\{[\s\S]*\}/, "")
+			.split(",")[0]
+			.trim();
+		if (
+			defaultImport &&
+			/^[A-Za-z_$][\w$]*$/.test(defaultImport) &&
+			sourceHasDefaultLifecycleExport(importedSource)
+		) {
+			aliases.add(defaultImport);
+		}
+	}
+	return aliases;
+};
+
+export const findFrontendLifecycleReadSideEffectFiles = (frontendSources) => {
+	return frontendSources
+		.filter((source) => {
+			const text = stripSourceNoise(source.text, { stripStrings: true });
+			const hasQueryReadPath =
+				/\b(?:useQuery|useSuspenseQuery|useInfiniteQuery|queryOptions)\s*\(/.test(
+					text,
+				) || /\bqueryFn\b/.test(text);
+			if (!hasQueryReadPath) {
+				return false;
+			}
+			if (
+				frontendQueryFunctionBlocks(source.text).some((block) =>
+					READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(block),
+				)
+			) {
+				return true;
+			}
+			const sameFileLifecycleHelpers = lifecycleHelperNamesInSource(source);
+			const queryFnBlocks = frontendQueryFunctionBlocks(source.text);
+			if (
+				queryFnBlocks.some((block) =>
+					blockCallsLifecycleHelper(block, sameFileLifecycleHelpers),
+				)
+			) {
+				return true;
+			}
+			const lifecycleAliases = frontendQueryFnLifecycleAliasNames({
+				frontendSources,
+				querySource: source,
+			});
+			return [...lifecycleAliases].some(
+				(alias) =>
+					[
+						new RegExp(`\\bqueryFn\\s*:\\s*${escapeRegex(alias)}\\b`),
+						...(alias === "queryFn" ? [/\bqueryFn\b/] : []),
+						new RegExp(
+							`\\bqueryFn\\s*:[\\s\\S]{0,600}\\b${escapeRegex(alias)}\\s*\\(`,
+						),
+					].some((pattern) => pattern.test(text)) ||
+					queryFnBlocks.some((block) =>
+						new RegExp(`\\b${escapeRegex(alias)}\\b`).test(block),
+					),
+			);
+		})
+		.map((source) => source.file_path);
+};
+
+export const REPEATED_IDENTITY_HELPER_PATTERN =
+	/\b(?:\w*refresh\w*|tokenRefresh|refresh_token|\w*current\w*|current_user|use(?:Current|User|Session)\w*|get(?:Current|Me|User|Session)\w*|fetch(?:Current|Me|User|Session)\w*|load(?:Current|Me|User|Session)\w*|\w*poll\w*|sessionPolling|requestExchange|queryFn|readHook)\b|\/me\b|current-user/i;
+
+export const repeatedIdentityHelperContext = ({ matchIndex, text }) => {
+	const before = text.slice(0, matchIndex);
+	const starts = [
+		...before.matchAll(
+			/\b(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*\{/g,
+		),
+		...before.matchAll(
+			/\b(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>\s*\{/g,
+		),
+		...before.matchAll(
+			// Match `def` and `async def`, and stop at the opening paren so
+			// multi-line / return-annotated signatures still yield the enclosing
+			// function name. Without `async` support the enclosing `async def`
+			// handler is missed and the code falls back to a raw text window,
+			// which false-matches ORM calls like `db.refresh(user)`.
+			/^[ \t]*(?:async[ \t]+)?def\s+([A-Za-z_][\w]*)\s*\(/gm,
+		),
+	].sort((left, right) => left.index - right.index);
+	const start = starts.at(-1);
+	if (!start) {
+		return text.slice(Math.max(0, matchIndex - 220), matchIndex);
+	}
+	return start[1] ?? "";
+};
+
+export const findRepeatedIdentityHelperFiles = (sources) =>
+	sources
+		.filter((source) => {
+			const text = stripSourceNoise(source.text, { stripStrings: true });
+			for (const match of text.matchAll(/\bcluebase\.identify\s*\(/g)) {
+				const context = repeatedIdentityHelperContext({
+					matchIndex: match.index,
+					text,
+				});
+				if (REPEATED_IDENTITY_HELPER_PATTERN.test(context)) {
+					return true;
+				}
+			}
+			return false;
+		})
+		.map((source) => source.file_path);
+
+export const pythonGetEndpointBlocks = (text) => {
+	const lines = stripSourceNoise(text).split(/\r?\n/);
+	const blocks = [];
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (!/^\s*@/.test(line)) continue;
+		const decoratorLines = [line];
+		let decoratorCursor = index + 1;
+		let parenBalance =
+			(line.match(/\(/g) ?? []).length - (line.match(/\)/g) ?? []).length;
+		while (decoratorCursor < lines.length && parenBalance > 0) {
+			decoratorLines.push(lines[decoratorCursor]);
+			parenBalance +=
+				(lines[decoratorCursor].match(/\(/g) ?? []).length -
+				(lines[decoratorCursor].match(/\)/g) ?? []).length;
+			decoratorCursor += 1;
+		}
+		const decoratorText = decoratorLines.join("\n");
+		const isGetDecorator =
+			/^\s*@(app|router|[\w.]+)\.get\s*\(/.test(decoratorText) ||
+			(/^\s*@(app|router|[\w.]+)\.api_route\s*\(/.test(decoratorText) &&
+				/\bmethods\s*=\s*\[[\s\S]*GET[\s\S]*\]/i.test(decoratorText));
+		if (!isGetDecorator) continue;
+		const block = [...decoratorLines];
+		let cursor = decoratorCursor;
+		while (cursor < lines.length && /^\s*@/.test(lines[cursor])) {
+			block.push(lines[cursor]);
+			cursor += 1;
+		}
+		const defLine = lines[cursor] ?? "";
+		if (!/^\s*(?:async\s+)?def\s+/.test(defLine)) continue;
+		const defIndent = defLine.match(/^\s*/)?.[0].length ?? 0;
+		block.push(defLine);
+		cursor += 1;
+		while (cursor < lines.length) {
+			const current = lines[cursor];
+			const indent = current.match(/^\s*/)?.[0].length ?? 0;
+			if (current.trim() && indent <= defIndent) break;
+			block.push(current);
+			cursor += 1;
+		}
+		blocks.push(block.join("\n"));
+	}
+	return blocks;
+};
+
+export const balancedBlockFrom = ({ close, open, startIndex, text }) => {
+	let depth = 0;
+	let started = false;
+	for (let index = startIndex; index < text.length; index += 1) {
+		const char = text[index];
+		if (char === open) {
+			depth += 1;
+			started = true;
+		} else if (char === close) {
+			depth -= 1;
+			if (started && depth === 0) {
+				return text.slice(startIndex, index + 1);
+			}
+		}
+	}
+	return text.slice(startIndex, Math.min(text.length, startIndex + 1600));
+};
+
+export const typescriptGetEndpointBlocks = (text) => {
+	const stripped = stripSourceNoise(text, { stripStrings: true });
+	const blocks = [
+		...stripped.matchAll(
+			/(?:^|\n)export\s+(?:async\s+)?function\s+GET\s*\([^)]*\)\s*(?::[^{]+)?\{/g,
+		),
+	].map((match) =>
+		balancedBlockFrom({
+			close: "}",
+			open: "{",
+			startIndex: match.index,
+			text: stripped,
+		}),
+	);
+	for (const match of stripped.matchAll(
+		/(?:^|\n)export\s+const\s+GET\s*(?::[^=]+)?=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)(?:\s*:[^=]+)?\s*=>\s*\{/g,
+	)) {
+		blocks.push(
+			balancedBlockFrom({
+				close: "}",
+				open: "{",
+				startIndex: match.index,
+				text: stripped,
+			}),
+		);
+	}
+	for (const match of stripped.matchAll(/(?:^|\n)\s*@Get\s*\([^)]*\)/g)) {
+		const nextDecoratorIndex = stripped
+			.slice(match.index + match[0].length)
+			.search(/\n\s*@[A-Za-z]/);
+		const sliceEnd =
+			nextDecoratorIndex >= 0
+				? match.index + match[0].length + nextDecoratorIndex
+				: stripped.length;
+		const methodSlice = stripped.slice(match.index, sliceEnd);
+		const bodyIndex = methodSlice.indexOf("{");
+		blocks.push(
+			bodyIndex >= 0
+				? balancedBlockFrom({
+						close: "}",
+						open: "{",
+						startIndex: match.index + bodyIndex,
+						text: stripped,
+					})
+				: methodSlice,
+		);
+	}
+	for (const match of stripped.matchAll(/\b(?:app|router)\.get\s*\(/g)) {
+		blocks.push(
+			balancedBlockFrom({
+				close: ")",
+				open: "(",
+				startIndex: match.index,
+				text: stripped,
+			}),
+		);
+	}
+	for (const match of stripped.matchAll(
+		/\b[A-Za-z_$][\w$]*\.get\s*\(\s*["'`][^"'`]*["'`]\s*,/g,
+	)) {
+		blocks.push(
+			balancedBlockFrom({
+				close: ")",
+				open: "(",
+				startIndex: match.index,
+				text: stripped,
+			}),
+		);
+	}
+	return blocks;
+};
+
+export const pythonFunctionBlockFrom = ({ startIndex, text }) => {
+	const startLineIndex = text.lastIndexOf("\n", startIndex) + 1;
+	const lines = text.slice(startLineIndex).split(/\r?\n/);
+	const firstLine = lines[0] ?? "";
+	const defIndent = firstLine.match(/^\s*/)?.[0].length ?? 0;
+	const block = [firstLine];
+	for (let index = 1; index < lines.length; index += 1) {
+		const line = lines[index];
+		const indent = line.match(/^\s*/)?.[0].length ?? 0;
+		if (line.trim() && indent <= defIndent) break;
+		block.push(line);
+	}
+	return block.join("\n");
+};
+
+export const lifecycleHelperNamesInSource = (source) => {
+	const stripped = stripSourceNoise(source.text, { stripStrings: true });
+	const names = [];
+	for (const match of stripped.matchAll(
+		/(?:^|\n)\s*(?:async\s+)?def\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*:/g,
+	)) {
+		const block = pythonFunctionBlockFrom({
+			startIndex: match.index,
+			text: stripped,
+		});
+		if (READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(block)) {
+			names.push(match[1]);
+		}
+	}
+	for (const match of stripped.matchAll(
+		/(?:^|\n)(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*\{/g,
+	)) {
+		const block = balancedBlockFrom({
+			close: "}",
+			open: "{",
+			startIndex: match.index,
+			text: stripped,
+		});
+		if (READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(block)) {
+			names.push(match[1]);
+		}
+	}
+	for (const match of stripped.matchAll(
+		/(?:^|\n)\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>\s*\{/g,
+	)) {
+		const block = balancedBlockFrom({
+			close: "}",
+			open: "{",
+			startIndex: match.index,
+			text: stripped,
+		});
+		if (READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(block)) {
+			names.push(match[1]);
+		}
+	}
+	return [...new Set(names)];
+};
+
+export const blockCallsLifecycleHelper = (block, helperNames) =>
+	helperNames.some((name) =>
+		new RegExp(`\\b${escapeRegex(name)}\\s*\\(`).test(block),
+	);
+
+export const backendImportCandidates = ({ importerPath, specifier }) => {
+	let base = null;
+	if (specifier.startsWith(".")) {
+		base = join(dirname(importerPath), specifier).replaceAll("\\", "/");
+	} else if (/^[A-Za-z_$][\w$.]*$/.test(specifier)) {
+		base = join(
+			dirname(importerPath),
+			specifier.replaceAll(".", "/"),
+		).replaceAll("\\", "/");
+	}
+	if (!base) return [];
+	return [
+		base,
+		`${base}.py`,
+		`${base}.ts`,
+		`${base}.tsx`,
+		`${base}.js`,
+		`${base}.jsx`,
+		join(base, "__init__.py").replaceAll("\\", "/"),
+		join(base, "index.ts").replaceAll("\\", "/"),
+		join(base, "index.tsx").replaceAll("\\", "/"),
+		join(base, "index.js").replaceAll("\\", "/"),
+		join(base, "index.jsx").replaceAll("\\", "/"),
+	];
+};
+
+export const backendImportedLifecycleAliasNames = ({ backendSources, source }) => {
+	const sourceByPath = new Map(
+		backendSources.map((entry) => [entry.file_path, entry]),
+	);
+	const aliases = new Set();
+	const text = stripSourceNoise(source.text);
+
+	for (const match of text.matchAll(
+		/\bimport\s+([^;]+?)\s+from\s+["']([^"']+)["']/g,
+	)) {
+		const importedSource = backendImportCandidates({
+			importerPath: source.file_path,
+			specifier: match[2],
+		})
+			.map((candidate) => sourceByPath.get(candidate))
+			.find(Boolean);
+		if (!importedSource) continue;
+		const exportedLifecycleNames = new Set(
+			lifecycleHelperNamesInSource(importedSource),
+		);
+		const importedSourceHasLifecycle = READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(
+			stripSourceNoise(importedSource.text, { stripStrings: true }),
+		);
+		const namedImport = /\{([\s\S]*)\}/.exec(match[1].trim());
+		if (!namedImport) continue;
+		for (const rawPart of namedImport[1].split(",")) {
+			const part = rawPart.trim();
+			if (!part) continue;
+			const [exported, local = exported] = part
+				.split(/\s+as\s+/i)
+				.map((entry) => entry.trim());
+			if (exportedLifecycleNames.has(exported) || importedSourceHasLifecycle) {
+				aliases.add(local);
+			}
+		}
+	}
+
+	for (const match of text.matchAll(
+		/\bfrom\s+([A-Za-z_$][\w$.]*|\.[A-Za-z_$][\w$.]*)\s+import\s+([^\n]+)/g,
+	)) {
+		const importedSource = backendImportCandidates({
+			importerPath: source.file_path,
+			specifier: match[1],
+		})
+			.map((candidate) => sourceByPath.get(candidate))
+			.find(Boolean);
+		if (!importedSource) continue;
+		const exportedLifecycleNames = new Set(
+			lifecycleHelperNamesInSource(importedSource),
+		);
+		const importedSourceHasLifecycle = READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(
+			stripSourceNoise(importedSource.text, { stripStrings: true }),
+		);
+		for (const rawPart of match[2].split(",")) {
+			const part = rawPart.trim();
+			if (!part || part === "*") continue;
+			const [exported, local = exported] = part
+				.split(/\s+as\s+/i)
+				.map((entry) => entry.trim());
+			if (exportedLifecycleNames.has(exported) || importedSourceHasLifecycle) {
+				aliases.add(local);
+			}
+		}
+	}
+
+	return [...aliases];
+};
+
+export const importedLocalNamesInSource = (source) => {
+	const text = stripSourceNoise(source.text);
+	const names = [];
+	for (const match of text.matchAll(
+		/\bimport\s+([^;]+?)\s+from\s+["'][^"']+["']/g,
+	)) {
+		const namedImport = /\{([\s\S]*)\}/.exec(match[1].trim());
+		if (!namedImport) continue;
+		for (const rawPart of namedImport[1].split(",")) {
+			const part = rawPart.trim();
+			if (!part) continue;
+			const [, local = part] = part
+				.split(/\s+as\s+/i)
+				.map((entry) => entry.trim());
+			names.push(local);
+		}
+	}
+	for (const match of text.matchAll(
+		/\bfrom\s+[A-Za-z_$.\w$]+\s+import\s+([^\n]+)/g,
+	)) {
+		for (const rawPart of match[1].split(",")) {
+			const part = rawPart.trim();
+			if (!part || part === "*") continue;
+			const [, local = part] = part
+				.split(/\s+as\s+/i)
+				.map((entry) => entry.trim());
+			names.push(local);
+		}
+	}
+	return names.filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+};
+
+export const findBackendLifecycleReadEndpointFiles = (backendSources) => {
+	const globalLifecycleHelperNames = new Set(
+		backendSources.flatMap((source) => lifecycleHelperNamesInSource(source)),
+	);
+	return backendSources
+		.filter((source) => {
+			const helperNames = [
+				...lifecycleHelperNamesInSource(source),
+				...backendImportedLifecycleAliasNames({ backendSources, source }),
+				...importedLocalNamesInSource(source).filter((name) =>
+					globalLifecycleHelperNames.has(name),
+				),
+			];
+			return [
+				...pythonGetEndpointBlocks(source.text),
+				...typescriptGetEndpointBlocks(source.text),
+			].some(
+				(block) =>
+					READ_SIDE_EFFECT_LIFECYCLE_PATTERN.test(block) ||
+					blockCallsLifecycleHelper(block, helperNames),
+			);
+		})
+		.map((source) => source.file_path);
+};
+
+export const lifecycleConceptPattern = (concepts) =>
+	new RegExp(
+		concepts
+			.flatMap((concept) => [
+				concept,
+				`${concept}[_-]?id`,
+				`${concept}Id`,
+				`${concept}ID`,
+			])
+			.map((value) => `\\b${value}\\b`)
+			.join("|"),
+		"i",
+	);
+
+export const identityBoundaryPattern = lifecycleConceptPattern([
+	"login",
+	"signin",
+	"sign_in",
+	"auth",
+	"token",
+	"session",
+	"user",
+]);
+export const frontendIdentityBoundaryPattern = lifecycleConceptPattern([
+	"login",
+	"signin",
+	"sign_in",
+	"auth",
+	"session",
+	"user",
+]);
+export const logoutBoundaryPattern = /\b(logout|signout|sign_out)\b/i;
+// Source app vocabulary that may represent the company boundary Cluebase maps to
+// organization. These are not Cluebase account/workspace concepts.
+export const companyBoundaryPattern = lifecycleConceptPattern([
+	"account",
+	"workspace",
+	"company",
+	"organization",
+	"org",
+	"tenant",
+]);
+