@amityco/social-plus-vise 0.4.0

package/dist/tools/project.js

@@ -0,0 +1,908 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readIfExists(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+export async function inspectProject(repoPath, surfacePath) {
+    const repoRoot = path.resolve(repoPath);
+    const surfaces = await detectProjectSurfaces(repoRoot);
+    const effectiveRoot = resolveSurfaceRoot(repoRoot, surfacePath);
+    const selectedSurface = surfacePath ? await surfaceForPath(repoRoot, effectiveRoot) : surfaceMatchingRoot(surfaces, repoRoot);
+    const { platforms, signals, designSignals } = await inspectRoot(effectiveRoot);
+    return {
+        repoRoot,
+        effectiveRoot,
+        selectedSurface,
+        platforms,
+        signals,
+        designSignals,
+        surfaces,
+    };
+}
+function resolveSurfaceRoot(repoRoot, surfacePath) {
+    if (!surfacePath) {
+        return repoRoot;
+    }
+    const resolved = path.resolve(repoRoot, surfacePath);
+    const relative = path.relative(repoRoot, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("surfacePath must stay inside repoPath.");
+    }
+    return resolved;
+}
+async function inspectRoot(root) {
+    const signals = [];
+    const candidates = [
+        ["android", "settings.gradle", "Gradle project settings"],
+        ["android", "settings.gradle.kts", "Gradle Kotlin project settings"],
+        ["android", "app/build.gradle", "Android app Gradle file"],
+        ["android", "app/build.gradle.kts", "Android app Gradle Kotlin file"],
+        ["flutter", "pubspec.yaml", "Flutter/Dart package manifest"],
+        ["ios", "Podfile", "CocoaPods project manifest"],
+        ["ios", "Package.swift", "Swift package manifest"],
+        ["typescript", "package.json", "JavaScript or TypeScript package manifest"],
+        ["typescript", "tsconfig.json", "TypeScript project config"],
+    ];
+    for (const [platform, relativeFile, reason] of candidates) {
+        if (await exists(path.join(root, relativeFile))) {
+            signals.push({ platform, file: relativeFile, reason });
+        }
+    }
+    const packageJson = await readIfExists(path.join(root, "package.json"));
+    if (packageJson.includes("react-native")) {
+        signals.push({
+            platform: "react-native",
+            file: "package.json",
+            reason: "react-native dependency or script signal",
+        });
+    }
+    const platforms = Array.from(new Set(signals.map((signal) => signal.platform)));
+    return { platforms, signals, designSignals: await detectDesignSignals(root) };
+}
+export const inspectProjectTool = {
+    name: "inspect_project",
+    description: "Inspect a customer repository and detect likely platform/framework signals.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: {
+                type: "string",
+                description: "Absolute or relative path to the customer repository root.",
+            },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await inspectProject(stringField(args, "repoPath"), optionalStringField(args, "surfacePath")));
+    },
+};
+export const validateSetupTool = {
+    name: "validate_setup",
+    description: "Check common social.plus setup risks for a detected platform.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            platform: {
+                type: "string",
+                description: "Optional platform override. If omitted, Vise uses project inspection.",
+            },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const inspection = await inspectProject(repoPath, optionalStringField(args, "surfacePath"));
+        const platform = optionalStringField(args, "platform") ?? inspection.platforms[0] ?? "unknown";
+        const findings = await validateSetup(inspection.effectiveRoot, platform);
+        return textResult({
+            platform,
+            surfacePath: inspection.selectedSurface?.path,
+            status: statusForFindings(findings),
+            findings,
+        });
+    },
+};
+export async function validateSetup(repoPath, platform) {
+    const root = path.resolve(repoPath);
+    const findings = [];
+    if (platform === "android") {
+        findings.push(...(await validateAndroid(root)));
+    }
+    if (platform === "flutter") {
+        findings.push(...(await validateFlutter(root)));
+    }
+    if (platform === "typescript" || platform === "react-native") {
+        findings.push(...(await validateTypeScript(root, platform)));
+    }
+    if (platform === "ios") {
+        findings.push(...(await validateIos(root)));
+    }
+    if (platform === "unknown") {
+        findings.push({
+            ruleId: "project.platform.detected",
+            severity: "warning",
+            message: "Could not detect a supported project platform.",
+            recommendation: "Point repoPath at the app root or provide a platform override.",
+        });
+    }
+    return findings;
+}
+async function validateAndroid(root) {
+    const findings = [];
+    const manifestPath = "app/src/main/AndroidManifest.xml";
+    const manifest = await readIfExists(path.join(root, manifestPath));
+    const buildFiles = await existingFiles(root, ["app/build.gradle", "app/build.gradle.kts", "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts"]);
+    const buildContent = await readMany(buildFiles);
+    const sourceFiles = await findFiles(root, [".kt", ".java"], 300);
+    const sourceContent = await readMany(sourceFiles);
+    const setupFiles = filesMatching(sourceContent, [/AmityCoreClient\s*\.\s*setup/, /AmityClient\s*\.\s*setup/]);
+    const loginFiles = filesMatching(sourceContent, [/AmityCoreClient\s*\.\s*login/, /AmityClient\s*\.\s*login/]);
+    const pushRegistrationFiles = filesMatching(sourceContent, [/registerPushNotification/, /enablePushNotification/, /PushNotification/]);
+    const pushUnregisterFiles = filesMatching(sourceContent, [/unregisterPushNotification/, /disablePushNotification/, /unregister.*DeviceToken/i]);
+    const liveDataFiles = filesMatching(sourceContent, [/LiveCollection/, /LiveObject/, /\.observe\s*\(/, /\.subscribe\s*\(/, /queryPosts\s*\(/, /getPost\s*\(/]);
+    if (!manifest) {
+        findings.push(finding("android.manifest.present", "warning", "No AndroidManifest.xml found at the default app path.", manifestPath, "Confirm the Android app module path, then validate permissions and Application wiring."));
+    }
+    else {
+        if (!manifest.includes("android.permission.INTERNET")) {
+            findings.push(finding("android.permission.internet", "error", "Android INTERNET permission is missing.", manifestPath, "Add `<uses-permission android:name=\"android.permission.INTERNET\" />` to the app manifest."));
+        }
+        if (!/<application\b[^>]*android:name=/.test(manifest)) {
+            findings.push(finding("android.application.class", "warning", "No custom Application class is declared in AndroidManifest.xml.", manifestPath, "Initialize social.plus once from an Application class instead of an Activity or composable lifecycle."));
+        }
+    }
+    if (!containsAny(buildContent, [/co\.amity\.android:amity-sdk/, /Amity-Social-Cloud-Android-SDK/, /com\.github\.AmityCo/])) {
+        findings.push(finding("android.dependency.sdk", "warning", "No obvious social.plus Android SDK dependency was found in Gradle files.", relativeFile(root, buildFiles[0]), "Add the SDK dependency from the Android quick-start docs and keep all Amity dependencies on compatible versions."));
+    }
+    else if (containsAny(buildContent, [/co\.amity\.android:amity-sdk:\+/, /co\.amity\.android:amity-sdk:latest/i, /version\s*=\s*["']\+["']/])) {
+        findings.push(finding("android.sdk.version.pinned", "warning", "The Android SDK dependency appears to use a floating version.", relativeFile(root, buildFiles[0]), "Pin the social.plus Android SDK to an explicit version or reviewed semver range so CI does not pick up unreviewed SDK APIs."));
+    }
+    if (setupFiles.length === 0) {
+        findings.push(finding("android.setup.present", "warning", "No obvious AmityCoreClient.setup call was found in Kotlin/Java files.", undefined, "Call SDK setup once during application startup before any social.plus API usage."));
+    }
+    else {
+        const activitySetup = setupFiles.find((file) => /Activity|Fragment|Composable|onCreateView/.test(sourceContent.get(file) ?? ""));
+        if (activitySetup) {
+            findings.push(finding("android.setup.lifecycle", "warning", "SDK setup appears near Activity/Fragment/UI lifecycle code.", relativeFile(root, activitySetup), "Prefer Application.onCreate so the SDK is initialized once and not reinitialized on screen recreation."));
+        }
+        if (!containsAnyForFiles(sourceContent, setupFiles, [/AmityEndpoint\./, /AmityRegion\./, /\bendpoint\s*=/, /\bregion\s*=/])) {
+            findings.push(finding("android.setup.region", "warning", "SDK setup was found but no explicit region/endpoint marker was detected.", relativeFile(root, setupFiles[0]), "Set the region/endpoint explicitly to match the customer's social.plus console project."));
+        }
+    }
+    if (loginFiles.length === 0) {
+        findings.push(finding("android.login.present", "warning", "No obvious social.plus login call was found.", undefined, "Call login after the app has a known user identity, and before subscribing to social.plus collections."));
+    }
+    else if (!containsAny(sourceContent, [/sessionWillRenewAccessToken/, /AmitySessionHandler/, /renewal\s*\.\s*renew\s*\(/])) {
+        findings.push(finding("android.session.renewal", "warning", "Login was found but no AmitySessionHandler with session renewal was detected.", relativeFile(root, loginFiles[0]), "Pass an AmitySessionHandler to login and call renewal.renew() in sessionWillRenewAccessToken so sessions refresh in production."));
+    }
+    if (pushRegistrationFiles.length > 0 && pushUnregisterFiles.length === 0) {
+        findings.push(finding("android.push.unregister.present", "warning", "Push registration was found but no obvious unregister call was detected.", relativeFile(root, pushRegistrationFiles[0]), "Unregister device tokens on logout or user switch so notifications are not sent to the wrong user."));
+    }
+    if (liveDataFiles.length > 0 && !containsAny(sourceContent, [/dispose\s*\(/, /Disposable/, /CompositeDisposable/, /clear\s*\(/, /removeObserver/, /unsubscribe/])) {
+        findings.push(finding("android.live.cleanup", "warning", "Live Object/Collection observation was found but no obvious cleanup was detected.", relativeFile(root, liveDataFiles[0]), "Dispose or unsubscribe observers when the Activity, Fragment, ViewModel, or composable lifecycle ends."));
+    }
+    findings.push(...validateLiteralGuardrails(root, "android", sourceContent));
+    findings.push(...validateLoggingHygiene(root, "android", sourceContent));
+    findings.push(...validateFeedUiStates(root, "android", sourceContent));
+    findings.push(...(await validateDesignReuse(root, "android", sourceContent)));
+    return findings;
+}
+async function validateFlutter(root) {
+    const findings = [];
+    const pubspec = await readIfExists(path.join(root, "pubspec.yaml"));
+    const dartFiles = await findFiles(path.join(root, "lib"), [".dart"], 300);
+    const dartContent = await readMany(dartFiles);
+    const setupFiles = filesMatching(dartContent, [/AmityCoreClient\s*\.\s*setup/]);
+    const loginFiles = filesMatching(dartContent, [/AmityCoreClient\s*\.\s*login/]);
+    const pushRegistrationFiles = filesMatching(dartContent, [/registerPushNotification/, /enablePushNotification/, /PushNotification/]);
+    const pushUnregisterFiles = filesMatching(dartContent, [/unregisterPushNotification/, /disablePushNotification/]);
+    const liveDataFiles = filesMatching(dartContent, [/LiveCollection/, /LiveObject/, /\.listen\s*\(/, /\.observe\s*\(/, /queryPosts\s*\(/, /getPost\s*\(/]);
+    if (!pubspec) {
+        findings.push(finding("flutter.pubspec.present", "warning", "No pubspec.yaml file was found.", "pubspec.yaml", "Point repoPath at the Flutter project root."));
+    }
+    else if (!/\bamity_sdk\s*:/.test(pubspec) && !pubspec.toLowerCase().includes("amity")) {
+        findings.push(finding("flutter.dependency.sdk", "warning", "No obvious social.plus/Amity dependency was found in pubspec.yaml.", "pubspec.yaml", "Add the Flutter SDK dependency from the Flutter quick-start docs."));
+    }
+    else if (/\bamity_sdk\s*:\s*(?:any|\*|latest)\b/i.test(pubspec)) {
+        findings.push(finding("flutter.sdk.version.pinned", "warning", "The Flutter SDK dependency appears to use a floating version.", "pubspec.yaml", "Pin amity_sdk to an explicit version or reviewed semver range so CI does not pick up unreviewed SDK APIs."));
+    }
+    if (setupFiles.length === 0) {
+        findings.push(finding("flutter.setup.present", "warning", "No obvious AmityCoreClient.setup call was found in lib/*.dart.", undefined, "Call AmityCoreClient.setup before any social.plus API usage."));
+    }
+    else {
+        if (!containsAny(dartContent, [/WidgetsFlutterBinding\.ensureInitialized\s*\(/])) {
+            findings.push(finding("flutter.binding.initialized", "warning", "SDK setup was found but WidgetsFlutterBinding.ensureInitialized was not detected.", relativeFile(root, setupFiles[0]), "Call WidgetsFlutterBinding.ensureInitialized before async SDK setup in main()."));
+        }
+        if (!containsAnyForFiles(dartContent, setupFiles, [/AmityEndpoint\./, /\bendpoint\s*:/, /\bregion\s*:/])) {
+            findings.push(finding("flutter.setup.region", "warning", "SDK setup was found but no explicit endpoint/region marker was detected.", relativeFile(root, setupFiles[0]), "Set the endpoint/region explicitly to match the customer's social.plus console project."));
+        }
+    }
+    if (loginFiles.length === 0) {
+        findings.push(finding("flutter.login.present", "warning", "No obvious AmityCoreClient.login call was found.", undefined, "Call login after the app has a known user identity and before social.plus queries/subscriptions."));
+    }
+    else if (!containsAny(dartContent, [/sessionWillRenewAccessToken/, /AmitySessionHandler/, /SessionHandler/, /renewal\s*\.\s*renew\s*\(/])) {
+        findings.push(finding("flutter.session.renewal", "warning", "Login was found but no AmitySessionHandler with session renewal was detected.", relativeFile(root, loginFiles[0]), "Implement an AmitySessionHandler and call renewal.renew() in sessionWillRenewAccessToken so sessions refresh in production."));
+    }
+    if (pushRegistrationFiles.length > 0 && pushUnregisterFiles.length === 0) {
+        findings.push(finding("flutter.push.unregister.present", "warning", "Push registration was found but no obvious unregister call was detected.", relativeFile(root, pushRegistrationFiles[0]), "Unregister device tokens on logout or user switch so notifications are not sent to the wrong user."));
+    }
+    if (liveDataFiles.length > 0 && !containsAny(dartContent, [/StreamSubscription/, /\.cancel\s*\(/, /dispose\s*\(/])) {
+        findings.push(finding("flutter.live.cleanup", "warning", "Live Object/Collection stream observation was found but no obvious cleanup was detected.", relativeFile(root, liveDataFiles[0]), "Store the subscription and cancel it from dispose or the owning lifecycle cleanup."));
+    }
+    findings.push(...validateLiteralGuardrails(root, "flutter", dartContent));
+    findings.push(...validateLoggingHygiene(root, "flutter", dartContent));
+    findings.push(...validateFeedUiStates(root, "flutter", dartContent));
+    findings.push(...(await validateDesignReuse(root, "flutter", dartContent)));
+    return findings;
+}
+async function validateTypeScript(root, platform) {
+    const findings = [];
+    const packageJson = await readIfExists(path.join(root, "package.json"));
+    const sourceFiles = await findFiles(root, [".ts", ".tsx", ".js", ".jsx"], 500);
+    const sourceContent = await readMany(sourceFiles);
+    const setupFiles = filesMatching(sourceContent, [/Client\s*\.\s*createClient/, /createClient\s*\(/]);
+    const loginFiles = filesMatching(sourceContent, [/Client\s*\.\s*login/, /\.login\s*\(/]);
+    const pushRegistrationFiles = filesMatching(sourceContent, [/registerPushNotification/, /enablePushNotification/, /PushNotification/]);
+    const pushUnregisterFiles = filesMatching(sourceContent, [/unregisterPushNotification/, /disablePushNotification/]);
+    const liveDataFiles = filesMatching(sourceContent, [/LiveCollection/, /LiveObject/, /\.subscribe\s*\(/, /\.observe\s*\(/, /queryPosts\s*\(/, /getPost\s*\(/, /onSnapshot/]);
+    if (!packageJson) {
+        findings.push(finding("typescript.package.present", "warning", "No package.json file was found.", "package.json", "Point repoPath at the TypeScript or React Native project root."));
+    }
+    else if (!packageJson.includes("@amityco/ts-sdk") && !packageJson.toLowerCase().includes("amity")) {
+        findings.push(finding("typescript.dependency.sdk", "warning", "No obvious social.plus/Amity package was found in package.json.", "package.json", "Add the TypeScript SDK dependency from the web quick-start docs."));
+    }
+    else if (isFloatingPackageDependency(packageJson, "@amityco/ts-sdk")) {
+        findings.push(finding(`${platform}.sdk.version.pinned`, "warning", "The TypeScript SDK dependency appears to use a floating version.", "package.json", "Pin @amityco/ts-sdk to an explicit version or reviewed semver range so CI does not pick up unreviewed SDK APIs."));
+    }
+    if (setupFiles.length === 0) {
+        findings.push(finding("typescript.client.create", "warning", "No obvious TypeScript client initialization pattern was found.", undefined, "Create the social.plus client before login and before API usage."));
+    }
+    else {
+        if (!containsAnyForFiles(sourceContent, setupFiles, [/\bregion\s*:/, /\bapiRegion\b/, /\bapiEndpoint\b/])) {
+            findings.push(finding("typescript.client.region", "warning", "Client initialization was found but no explicit region or endpoint marker was detected.", relativeFile(root, setupFiles[0]), "Pass the region or endpoint that matches the customer's social.plus console project."));
+        }
+        const renderCycleSetup = setupFiles.find((file) => /useEffect|function\s+[A-Z]\w*\s*\(|const\s+[A-Z]\w*\s*=/.test(sourceContent.get(file) ?? ""));
+        if (renderCycleSetup && platform === "react-native") {
+            findings.push(finding("react-native.setup.lifecycle", "warning", "Client setup appears near component lifecycle code.", relativeFile(root, renderCycleSetup), "Keep client setup in a stable app initialization module to avoid duplicate initialization on remount."));
+        }
+    }
+    if (loginFiles.length === 0) {
+        findings.push(finding("typescript.login.present", "warning", "No obvious social.plus login call was found.", undefined, "Call login after the app has a known user identity, and await it before subscribing to live collections."));
+    }
+    if (loginFiles.length > 0 && !containsAny(sourceContent, [/sessionWillRenewAccessToken/, /sessionHandler/, /renewal\.renew/])) {
+        findings.push(finding(`${platform}.session.renewal`, "warning", "Login was found but no access-token renewal handler marker was detected.", relativeFile(root, loginFiles[0]), "Implement a session handler that renews the access token (sessionWillRenewAccessToken + renewal.renew()) so sessions refresh in production."));
+    }
+    if (pushRegistrationFiles.length > 0 && pushUnregisterFiles.length === 0) {
+        findings.push(finding(`${platform}.push.unregister.present`, "warning", "Push registration was found but no obvious unregister call was detected.", relativeFile(root, pushRegistrationFiles[0]), "Unregister device tokens on logout or user switch so notifications are not sent to the wrong user."));
+    }
+    if (liveDataFiles.length > 0 && !containsAny(sourceContent, [/unsubscribe\s*\(/, /\.unsubscribe\s*\(/, /return\s*\(\s*\)\s*=>/, /return\s+unsubscribe/, /AbortController/, /cleanup/i])) {
+        findings.push(finding(`${platform}.live.cleanup`, "warning", "Live Object/Collection subscription was found but no obvious cleanup was detected.", relativeFile(root, liveDataFiles[0]), "Return or call the unsubscribe cleanup from the owning component, route, or store lifecycle."));
+    }
+    findings.push(...validateLiteralGuardrails(root, platform, sourceContent));
+    findings.push(...validateLoggingHygiene(root, platform, sourceContent));
+    findings.push(...validateFeedUiStates(root, platform, sourceContent));
+    findings.push(...(await validateDesignReuse(root, platform, sourceContent)));
+    if (platform === "typescript") {
+        findings.push(...(await validateTypeScriptEnvSecretHygiene(root, sourceContent)));
+    }
+    return findings;
+}
+async function validateTypeScriptEnvSecretHygiene(root, sourceContent) {
+    const findings = [];
+    const envSecretFiles = await committedEnvSecretFiles(root);
+    for (const file of envSecretFiles) {
+        findings.push(finding("typescript.secret.committed-env", "warning", "A local env file appears to contain a social.plus secret.", file, "Do not commit .env files with real API keys. Commit a placeholder .env.example and keep local env files ignored."));
+    }
+    if (usesEnvSecretConfig(sourceContent)) {
+        const gitignore = await readIfExists(path.join(root, ".gitignore"));
+        if (!gitignoreIgnoresEnvFiles(gitignore)) {
+            findings.push(finding("typescript.secret.env-gitignore", "warning", "Source uses env-based social.plus secret config but .gitignore does not ignore local env files.", ".gitignore", "Add .env, .env.local, and environment-specific local env files to .gitignore."));
+        }
+        const hasExample = await exists(path.join(root, ".env.example")) || await exists(path.join(root, ".env.sample"));
+        if (!hasExample) {
+            findings.push(finding("typescript.secret.env-example", "warning", "Source uses env-based social.plus secret config but no env example file was found.", ".env.example", "Commit .env.example with placeholder keys so agents and developers know which values to provide locally."));
+        }
+    }
+    return findings;
+}
+// Logging hygiene: customers shipping debug logs of secret-shaped values is a
+// real failure mode (console.log("client", apiKey) escapes to production).
+// Per platform we match the relevant log function calls; the secret-shaped
+// regex is shared. Returns at most one finding per scan to keep noise low.
+function validateLoggingHygiene(root, platform, sourceContent) {
+    const logCallPattern = LOGGING_CALL_PATTERNS_BY_PLATFORM[platform];
+    if (!logCallPattern) {
+        return [];
+    }
+    const secretShape = /\b(api[_-]?key|api[_-]?secret|access[_-]?token|refresh[_-]?token|bearer[_-]?token|client[_-]?secret|secret[_-]?key)\b/i;
+    for (const [file, content] of sourceContent) {
+        for (const line of content.split(/\r?\n/)) {
+            if (!logCallPattern.test(line)) {
+                continue;
+            }
+            if (!secretShape.test(line)) {
+                continue;
+            }
+            // Allow commented-out lines (//, #, /*); rough but kills the obvious
+            // false positives like documentation snippets.
+            const trimmed = line.trimStart();
+            if (trimmed.startsWith("//") || trimmed.startsWith("#") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+                continue;
+            }
+            return [
+                finding(`${platform}.logging.no-secret-in-log`, "warning", "A logging call appears to reference a secret-shaped identifier (apiKey, accessToken, etc.).", relativeFile(root, file), "Do not log secret-shaped values. Drop the log line, redact the value, or attest that the value being logged is a placeholder."),
+            ];
+        }
+    }
+    return [];
+}
+// Design system reuse: when the project has detected theme / token / design-
+// system files (via detectDesignSignals), at least one other source file
+// should reference one of those files by basename or class identifier.
+// Tolerant heuristic — false negatives are accepted (the agent might use a
+// theme provider context implicitly); the goal is to catch the obvious
+// "agent ignored the detected design system and wrote inline styles."
+async function validateDesignReuse(root, platform, sourceContent) {
+    const designSignals = await detectDesignSignals(root);
+    if (designSignals.length === 0) {
+        return [];
+    }
+    // Build reference markers per design file. For each design file we look for
+    // its basename (without extension) AND its PascalCase identifier guess. A
+    // source file that imports / mentions any marker counts as a reference.
+    const markersByFile = [];
+    for (const signal of designSignals) {
+        const base = path.basename(signal.file).replace(/\.(ts|tsx|js|jsx|dart|kt|java|swift|xml|css)$/i, "");
+        const pascal = toPascalCase(base);
+        const markers = new Set([base]);
+        if (pascal && pascal !== base) {
+            markers.add(pascal);
+        }
+        markersByFile.push({ file: signal.file, markers: [...markers] });
+    }
+    // Resolve design file absolute paths so we can skip them when scanning.
+    const designAbsolutePaths = new Set(designSignals.map((signal) => path.resolve(root, signal.file)));
+    for (const [file, content] of sourceContent) {
+        if (designAbsolutePaths.has(file)) {
+            continue;
+        }
+        for (const { markers } of markersByFile) {
+            for (const marker of markers) {
+                if (!marker || marker.length < 3) {
+                    continue;
+                }
+                if (content.includes(marker)) {
+                    return [];
+                }
+            }
+        }
+    }
+    return [
+        finding(`${platform}.design.reuse-detected-tokens`, "warning", `Detected design source(s) (${designSignals.map((s) => s.file).slice(0, 3).join(", ")}) are not referenced by any other source file.`, designSignals[0].file, "Import or reference the detected design tokens / theme module from your new UI code instead of inlining colors, spacing, or typography. Attest with evidence (the import path) if you use an implicit theme provider context."),
+    ];
+}
+function toPascalCase(snakeOrKebab) {
+    return snakeOrKebab
+        .split(/[_\-\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}
+// Feed UI states: when a source file observes a live data stream/collection,
+// it should also render loading / empty / error states. The heuristic is
+// per-platform: detect a live-data observation pattern in a file, then check
+// that file for at least one state marker. Returns at most one finding to
+// keep noise low.
+function validateFeedUiStates(root, platform, sourceContent) {
+    const observationPatterns = LIVE_DATA_OBSERVATION_PATTERNS_BY_PLATFORM[platform];
+    const statePatterns = UI_STATE_PATTERNS_BY_PLATFORM[platform];
+    if (!observationPatterns || !statePatterns) {
+        return [];
+    }
+    for (const [file, content] of sourceContent) {
+        const observes = observationPatterns.some((pattern) => pattern.test(content));
+        if (!observes) {
+            continue;
+        }
+        const hasStates = statePatterns.some((pattern) => pattern.test(content));
+        if (hasStates) {
+            continue;
+        }
+        return [
+            finding(`${platform}.feed.ui-states-present`, "warning", "A source file observes a live data stream/collection but does not appear to render loading, empty, or error states.", relativeFile(root, file), "Render loading / empty / error states next to the live-data binding. Common markers: isLoading, error, empty, CircularProgressIndicator (Flutter), ProgressView (SwiftUI), CircularProgressIndicator (Compose)."),
+        ];
+    }
+    return [];
+}
+const LIVE_DATA_OBSERVATION_PATTERNS_BY_PLATFORM = {
+    typescript: [/PostRepository\.getPosts/, /\.subscribe\s*\(/, /\.observe\s*\(/, /onSnapshot/],
+    "react-native": [/PostRepository\.getPosts/, /\.subscribe\s*\(/, /\.observe\s*\(/, /onSnapshot/],
+    flutter: [/\.listen\s*\(/, /StreamSubscription/, /getStreamController\s*\(/, /AmityCollection/, /AmityObject/],
+    // Kotlin uses trailing lambdas — `.observe { ... }` is more common than
+    // `.observe(...)`. Match either form.
+    android: [/LiveCollection/, /LiveObject/, /\.observe\s*[({]/, /\.subscribe\s*[({]/, /\.collectAsState\b/, /AmitySocialClient\.newPostRepository/, /AmityCollection/],
+    // Swift trailing-closure form: `.observe { snapshot in ... }`.
+    ios: [/AmityCollection/, /AmityObject/, /\.observe\s*[({]/, /getPosts\s*\(/, /queryPosts\s*\(/],
+};
+const UI_STATE_PATTERNS_BY_PLATFORM = {
+    typescript: [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bempty\b/i, /\.length\s*===?\s*0/, /\busestate\b/i],
+    "react-native": [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bempty\b/i, /\.length\s*===?\s*0/, /ActivityIndicator/],
+    flutter: [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bisEmpty\b/, /CircularProgressIndicator/, /AsyncSnapshot/, /ConnectionState/],
+    android: [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bempty\b/i, /CircularProgressIndicator/, /LoadingState/, /\.collectAsState\b/],
+    ios: [/\bisLoading\b/i, /\bloading\b/, /\berror\b/, /\bempty\b/i, /ProgressView/, /LoadingState/, /AsyncImage/],
+};
+const LOGGING_CALL_PATTERNS_BY_PLATFORM = {
+    android: /\b(?:Log\.[a-z]\s*\(|println\s*\(|print\s*\()/,
+    flutter: /\b(?:print\s*\(|debugPrint\s*\(|log\s*\()/,
+    ios: /\b(?:print\s*\(|NSLog\s*\(|os_log\s*\(|Logger\b[^)]*\.\s*(?:log|info|debug|notice|error|fault)\s*\()/,
+    typescript: /\bconsole\s*\.\s*(?:log|info|warn|error|debug|trace)\s*\(/,
+    "react-native": /\bconsole\s*\.\s*(?:log|info|warn|error|debug|trace)\s*\(/,
+};
+function validateLiteralGuardrails(root, platform, sourceContent) {
+    const findings = [];
+    const feedTarget = firstLiteralAssignment(sourceContent, [
+        /\bcommunityId\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
+        /\btargetId\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
+        /\bfeedId\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
+        /\bchannelId\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
+    ]);
+    if (feedTarget && !isAllowedPlaceholder(feedTarget.value)) {
+        findings.push(finding(`${platform}.feed.target.literal`, "warning", `A hardcoded feed target literal was found: ${feedTarget.name}.`, relativeFile(root, feedTarget.file), "Do not invent or hardcode communityId, targetId, feedId, or channelId. Ask the user for the target or use an existing app-owned selection/create flow."));
+    }
+    const inlineApiKey = firstLiteralAssignment(sourceContent, [
+        /\bapiKey\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
+        /\bapi_key\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
+        /\bapi-key\b\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
+    ]);
+    if (inlineApiKey && !isAllowedPlaceholder(inlineApiKey.value)) {
+        findings.push(finding(`${platform}.secret.inline-api-key`, "warning", "A social.plus API key appears to be hardcoded in source.", relativeFile(root, inlineApiKey.file), "Use the host app's environment/config pattern instead of committing API keys directly into source files."));
+    }
+    // Hardcoded user identity — every benchmark Pure MCP failure mode included
+    // `userId: "current-user"` or similar. The user identity should come from
+    // the host app's auth state, not a literal in source.
+    const literalUserId = firstLiteralAssignment(sourceContent, [
+        /\buserId\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
+        /\buser_id\s*[:=]\s*["'`]([^"'`]+)["'`]/i,
+        /\.login\s*\(\s*["'`]([^"'`]+)["'`]/i,
+        /\.login\s*\(\s*userId\s*:\s*["'`]([^"'`]+)["'`]/i,
+    ]);
+    if (literalUserId && !isAllowedPlaceholder(literalUserId.value)) {
+        findings.push(finding(`${platform}.auth.no-literal-user-id`, "warning", `A hardcoded user identity literal was found: ${literalUserId.name}.`, relativeFile(root, literalUserId.file), "Do not hardcode a userId in source. Read the authenticated user from the host app's auth state (current session, route param, user-store hook, etc.)."));
+    }
+    return findings;
+}
+function firstLiteralAssignment(contents, patterns) {
+    for (const [file, content] of contents) {
+        for (const pattern of patterns) {
+            pattern.lastIndex = 0;
+            const match = pattern.exec(content);
+            if (match?.[1]) {
+                const name = match[0].split(/[=:]/)[0]?.trim() ?? "literal";
+                return { file, name, value: match[1].trim() };
+            }
+        }
+    }
+    return undefined;
+}
+function isAllowedPlaceholder(value) {
+    const normalized = value.toLowerCase().trim();
+    return [
+        "",
+        "api-key",
+        "your-api-key",
+        "your_api_key",
+        "provided-by-customer",
+        "customer-provided",
+        "replace-me",
+        "todo",
+        "community-id",
+        "community_id",
+        "target-id",
+        "target_id",
+        "feed-id",
+        "feed_id",
+        "channel-id",
+        "channel_id",
+        "user-id",
+        "user_id",
+        "your-user-id",
+        "your_user_id",
+        "test-user",
+        "demo-user",
+        "<userid>",
+        "<user_id>",
+    ].includes(normalized);
+}
+function isFloatingPackageDependency(packageJson, dependencyName) {
+    let parsed;
+    try {
+        parsed = JSON.parse(packageJson);
+    }
+    catch {
+        return false;
+    }
+    const version = parsed.dependencies?.[dependencyName] ??
+        parsed.devDependencies?.[dependencyName] ??
+        parsed.peerDependencies?.[dependencyName] ??
+        parsed.optionalDependencies?.[dependencyName];
+    if (!version) {
+        return false;
+    }
+    return /^(?:latest|\*|x|X)$/i.test(version.trim());
+}
+function usesEnvSecretConfig(sourceContent) {
+    return containsAny(sourceContent, [
+        /import\.meta\.env\.[A-Z0-9_]*(?:AMITY|SOCIAL_PLUS|SOCIALPLUS)[A-Z0-9_]*(?:API[_-]?KEY|KEY)/i,
+        /process\.env\.[A-Z0-9_]*(?:AMITY|SOCIAL_PLUS|SOCIALPLUS)[A-Z0-9_]*(?:API[_-]?KEY|KEY)/i,
+    ]);
+}
+async function committedEnvSecretFiles(root) {
+    const candidates = [".env", ".env.local", ".env.production", ".env.development"];
+    const found = [];
+    for (const candidate of candidates) {
+        const content = await readIfExists(path.join(root, candidate));
+        if (!content) {
+            continue;
+        }
+        const hasSecret = content
+            .split(/\r?\n/)
+            .some((line) => {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#")) {
+                return false;
+            }
+            const [key, ...rest] = trimmed.split("=");
+            const value = rest.join("=").trim().replace(/^["']|["']$/g, "");
+            return /(?:AMITY|SOCIAL_PLUS|SOCIALPLUS).*?(?:API[_-]?KEY|KEY)/i.test(key ?? "") && !isAllowedPlaceholder(value);
+        });
+        if (hasSecret) {
+            found.push(candidate);
+        }
+    }
+    return found;
+}
+function gitignoreIgnoresEnvFiles(gitignore) {
+    return gitignore
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .some((line) => line === ".env" || line === ".env*" || line === ".env.local" || line === "*.env" || line === ".env.*");
+}
+async function validateIos(root) {
+    const findings = [];
+    const manifestFiles = await existingFiles(root, ["Podfile", "Package.swift"]);
+    const manifestContent = await readMany(manifestFiles);
+    const swiftFiles = await findFiles(root, [".swift"], 400);
+    const swiftContent = await readMany(swiftFiles);
+    const setupFiles = filesMatching(swiftContent, [/AmityClient\s*\(/, /AmityClient\s*\.\s*setup/]);
+    const loginFiles = filesMatching(swiftContent, [/\.login\s*\(/, /client\.login\s*\(/]);
+    const pushRegistrationFiles = filesMatching(swiftContent, [/registerPushNotification/, /enablePushNotification/, /didRegisterForRemoteNotifications/]);
+    const pushUnregisterFiles = filesMatching(swiftContent, [/unregisterPushNotification/, /disablePushNotification/]);
+    const liveDataFiles = filesMatching(swiftContent, [/AmityCollection/, /AmityObject/, /\.observe\s*\(/, /getPost\s*\(/, /queryPosts\s*\(/]);
+    if (manifestFiles.length === 0) {
+        findings.push(finding("ios.dependency.manifest", "warning", "No Podfile or Package.swift was found.", undefined, "Point repoPath at the iOS project root or verify the dependency manager manually."));
+    }
+    else if (!containsAny(manifestContent, [/Amity/i, /AmitySDK/i])) {
+        findings.push(finding("ios.dependency.sdk", "warning", "No obvious social.plus/Amity dependency was found in Podfile or Package.swift.", relativeFile(root, manifestFiles[0]), "Add the iOS SDK dependency from the iOS quick-start docs."));
+    }
+    else if (containsAny(manifestContent, [/\.package\s*\([^)]*\bbranch\s*:/s, /pod\s+['"][^'"]*Amity[^'"]*['"]\s*$/m])) {
+        findings.push(finding("ios.sdk.version.pinned", "warning", "The iOS SDK dependency appears to use a floating branch or unspecified CocoaPods version.", relativeFile(root, manifestFiles[0]), "Pin the social.plus iOS SDK to an explicit version or reviewed semver range so CI does not pick up unreviewed SDK APIs."));
+    }
+    if (setupFiles.length === 0) {
+        findings.push(finding("ios.setup.present", "warning", "No obvious AmityClient initialization was found in Swift files.", undefined, "Initialize AmityClient before login and before social.plus API usage."));
+    }
+    else {
+        if (!containsAnyForFiles(swiftContent, setupFiles, [/\bregion\s*:/, /\.SG\b|\.EU\b|\.US\b/])) {
+            findings.push(finding("ios.setup.region", "warning", "AmityClient initialization was found but no explicit region marker was detected.", relativeFile(root, setupFiles[0]), "Set the region explicitly to match the customer's social.plus console project."));
+        }
+        // Setup must happen during app startup (AppDelegate.application(_:didFinishLaunchingWithOptions:),
+        // @main App.init, or a UIApplicationDelegate willFinishLaunching), not in
+        // a view/scene lifecycle method that re-runs across screens.
+        const lifecycleSetup = setupFiles.find((file) => /(viewDidLoad|viewWillAppear|viewWillDisappear|viewDidAppear|viewDidDisappear|scene\s*\(_:willConnectTo)/.test(swiftContent.get(file) ?? ""));
+        if (lifecycleSetup) {
+            findings.push(finding("ios.setup.lifecycle", "warning", "AmityClient initialization appears inside a view or scene lifecycle method.", relativeFile(root, lifecycleSetup), "Run AmityClient setup during app process startup (AppDelegate.application(_:didFinishLaunchingWithOptions:) or @main App.init) so it does not re-initialize on screen transitions."));
+        }
+    }
+    if (loginFiles.length === 0) {
+        findings.push(finding("ios.login.present", "warning", "No obvious social.plus login call was found.", undefined, "Call login after the app has a known user identity and handle session renewal for production auth."));
+    }
+    else if (!containsAny(swiftContent, [/sessionWillRenewAccessToken/, /AmitySessionHandler/, /renewal\.renew\s*\(/])) {
+        findings.push(finding("ios.session.renewal", "warning", "Login was found but no AmitySessionHandler with sessionWillRenewAccessToken / renewal.renew() was detected.", relativeFile(root, loginFiles[0]), "Implement AmitySessionHandler and call renewal.renew() in sessionWillRenewAccessToken so the session can refresh in production."));
+    }
+    if (pushRegistrationFiles.length > 0 && pushUnregisterFiles.length === 0) {
+        findings.push(finding("ios.push.unregister.present", "warning", "Push registration was found but no obvious unregister call was detected.", relativeFile(root, pushRegistrationFiles[0]), "Unregister device tokens on logout or user switch so notifications are not sent to the wrong user."));
+    }
+    if (liveDataFiles.length > 0 && !containsAny(swiftContent, [/AmityNotificationToken/, /\.invalidate\s*\(/, /deinit/, /viewWillDisappear/])) {
+        findings.push(finding("ios.live.cleanup", "warning", "Live Object/Collection observation was found but no obvious cleanup was detected.", relativeFile(root, liveDataFiles[0]), "Keep the notification token and invalidate or release it when the view/controller lifecycle ends."));
+    }
+    findings.push(...validateLiteralGuardrails(root, "ios", swiftContent));
+    findings.push(...validateLoggingHygiene(root, "ios", swiftContent));
+    findings.push(...validateFeedUiStates(root, "ios", swiftContent));
+    findings.push(...(await validateDesignReuse(root, "ios", swiftContent)));
+    return findings;
+}
+function statusForFindings(findings) {
+    if (findings.some((finding) => finding.severity === "error")) {
+        return "blocked";
+    }
+    return findings.length === 0 ? "no-obvious-issues" : "needs-review";
+}
+function finding(ruleId, severity, message, file, recommendation) {
+    return { ruleId, severity, message, file, recommendation };
+}
+async function existingFiles(root, relativeFiles) {
+    const files = [];
+    for (const relativePath of relativeFiles) {
+        const absolutePath = path.join(root, relativePath);
+        if (await exists(absolutePath)) {
+            files.push(absolutePath);
+        }
+    }
+    return files;
+}
+async function detectProjectSurfaces(repoRoot) {
+    const candidateDirectories = await findSurfaceCandidateDirectories(repoRoot, 3);
+    const surfaces = [];
+    for (const directory of candidateDirectories) {
+        const { platforms, signals, designSignals } = await inspectRoot(directory);
+        if (platforms.length === 0) {
+            continue;
+        }
+        const relativePath = normalizeSurfacePath(path.relative(repoRoot, directory));
+        surfaces.push({
+            id: relativePath === "." ? "root" : relativePath,
+            path: relativePath,
+            platforms,
+            signals: signals.map((signal) => ({
+                ...signal,
+                file: relativePath === "." ? signal.file : path.posix.join(relativePath, signal.file),
+            })),
+            designSignalCount: designSignals.length,
+        });
+    }
+    return surfaces.sort((a, b) => {
+        if (a.path === ".") {
+            return -1;
+        }
+        if (b.path === ".") {
+            return 1;
+        }
+        return a.path.localeCompare(b.path);
+    });
+}
+async function findSurfaceCandidateDirectories(root, maxDepth) {
+    const found = new Set([root]);
+    async function walk(directory, depth) {
+        if (depth >= maxDepth) {
+            return;
+        }
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || shouldSkipDirectory(entry.name)) {
+                continue;
+            }
+            const entryPath = path.join(directory, entry.name);
+            found.add(entryPath);
+            await walk(entryPath, depth + 1);
+        }
+    }
+    await walk(root, 0);
+    return Array.from(found);
+}
+async function surfaceForPath(repoRoot, effectiveRoot) {
+    const { platforms, signals, designSignals } = await inspectRoot(effectiveRoot);
+    const relativePath = normalizeSurfacePath(path.relative(repoRoot, effectiveRoot));
+    return {
+        id: relativePath === "." ? "root" : relativePath,
+        path: relativePath,
+        platforms,
+        signals,
+        designSignalCount: designSignals.length,
+    };
+}
+function surfaceMatchingRoot(surfaces, repoRoot) {
+    return surfaces.find((surface) => surface.path === normalizeSurfacePath(path.relative(repoRoot, repoRoot)));
+}
+function normalizeSurfacePath(relativePath) {
+    if (!relativePath || relativePath === ".") {
+        return ".";
+    }
+    return relativePath.split(path.sep).join(path.posix.sep);
+}
+function shouldSkipDirectory(name) {
+    return ["node_modules", ".git", "build", ".dart_tool", "dist", "coverage", ".next"].includes(name);
+}
+async function detectDesignSignals(root) {
+    const signals = [];
+    const candidateFiles = [
+        ["styles", "tailwind.config.js", "Tailwind design configuration"],
+        ["styles", "tailwind.config.cjs", "Tailwind design configuration"],
+        ["styles", "tailwind.config.mjs", "Tailwind design configuration"],
+        ["styles", "tailwind.config.ts", "Tailwind design configuration"],
+        ["theme", "src/theme.ts", "TypeScript theme module"],
+        ["theme", "src/theme.tsx", "TypeScript theme module"],
+        ["theme", "src/theme/index.ts", "TypeScript theme module"],
+        ["theme", "src/theme/index.tsx", "TypeScript theme module"],
+        ["tokens", "src/tokens.ts", "TypeScript design token module"],
+        ["tokens", "src/tokens/index.ts", "TypeScript design token module"],
+        ["tokens", "src/design-tokens.ts", "TypeScript design token module"],
+        ["tokens", "src/design-system/tokens.ts", "TypeScript design system token module"],
+        ["components", "src/design-system/components.ts", "TypeScript design system component registry"],
+        ["theme", "src/styles/theme.ts", "TypeScript theme module"],
+        ["theme", "src/styles/theme/index.ts", "TypeScript theme module"],
+        ["tokens", "src/styles/tokens.ts", "TypeScript design token module"],
+        ["styles", "src/styles/globals.css", "Global stylesheet"],
+        ["styles", "src/app/globals.css", "Global stylesheet"],
+        ["styles", "app/globals.css", "Global stylesheet"],
+        ["theme", "theme/index.ts", "TypeScript theme module"],
+        ["tokens", "tokens/index.ts", "TypeScript design token module"],
+        ["components", "components/ui/button.tsx", "Reusable UI component convention"],
+        ["components", "src/components/ui/button.tsx", "Reusable UI component convention"],
+        ["theme", "lib/theme.dart", "Flutter theme module"],
+        ["theme", "lib/app_theme.dart", "Flutter app theme module"],
+        ["theme", "lib/theme/app_theme.dart", "Flutter app theme module"],
+        ["theme", "lib/core/theme/app_theme.dart", "Flutter app theme module"],
+        ["theme", "lib/presentation/theme/app_theme.dart", "Flutter app theme module"],
+        ["tokens", "lib/design_tokens.dart", "Flutter design token module"],
+        ["tokens", "lib/theme/design_tokens.dart", "Flutter design token module"],
+        ["tokens", "app/src/main/res/values/colors.xml", "Android color resources"],
+        ["theme", "app/src/main/res/values/themes.xml", "Android theme resources"],
+    ];
+    for (const [kind, relativePath, reason] of candidateFiles) {
+        if (await exists(path.join(root, relativePath))) {
+            signals.push({ kind, file: relativePath, reason });
+        }
+    }
+    const sourceFiles = await findFiles(root, [".ts", ".tsx", ".js", ".jsx", ".dart", ".css", ".swift", ".kt", ".java"], 400);
+    const sourceContent = await readMany(sourceFiles);
+    const tokenLikeFiles = filesMatching(sourceContent, [
+        /ThemeData\s*\(/,
+        /ColorScheme\./,
+        /createTheme\s*\(/,
+        /extendTheme\s*\(/,
+        /createMuiTheme\s*\(/,
+        /ThemeProvider\b/,
+        /ChakraProvider\b/,
+        /TamaguiProvider\b/,
+        /NativeWindStyleSheet\b/,
+        /designTokens/,
+        /designSystem/,
+        /tokens\s*=/,
+        /\btheme\s*=\s*{/,
+        /\btheme\s*:\s*{/,
+        /\bcolors\s*:\s*{/,
+        /\bspacing\s*:\s*{/,
+        /\bradius\s*:\s*{/,
+        /--[a-z0-9-]+:\s*[^;]+;/i,
+        /\b(?:enum|struct)\s+(?:AppTheme|Theme|Colors|Spacing|Tokens|DesignSystem|DesignTokens|Typography|Radius)\b/,
+        /\bextension\s+(?:UIColor|Color)\b/,
+        /\bstatic\s+let\s+\w+\s*(?::\s*\w+)?\s*=\s*Color\s*\(/,
+        /\b(?:fun|val|object)\s+(?:lightColorScheme|darkColorScheme|MaterialTheme)\b/,
+        /\bMaterialTheme\s*\(/,
+        /\b(?:lightColorScheme|darkColorScheme)\s*\(/,
+        /\b(?:val|var)\s+\w+\s*=\s*Color\s*\(\s*0x[0-9A-Fa-f]{6,8}\s*\)/,
+        /\b(?:object|class)\s+(?:AppTheme|AppColors|AppTypography|AppSpacing|Tokens|DesignTokens)\b/,
+    ]);
+    for (const file of tokenLikeFiles) {
+        const relativePath = relativeFile(root, file);
+        if (relativePath && !signals.some((signal) => signal.file === relativePath)) {
+            signals.push({
+                kind: inferDesignKind(relativePath),
+                file: relativePath,
+                reason: "Source content contains theme, token, or CSS custom property markers.",
+            });
+        }
+    }
+    return signals.slice(0, 20);
+}
+function inferDesignKind(relativePath) {
+    const normalized = relativePath.toLowerCase();
+    if (normalized.includes("token")) {
+        return "tokens";
+    }
+    if (normalized.includes("component")) {
+        return "components";
+    }
+    if (normalized.endsWith(".css")) {
+        return "styles";
+    }
+    return "theme";
+}
+async function findFiles(root, extensions, maxFiles) {
+    const found = [];
+    async function walk(directory) {
+        if (found.length >= maxFiles) {
+            return;
+        }
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (found.length >= maxFiles) {
+                return;
+            }
+            if (shouldSkipDirectory(entry.name)) {
+                continue;
+            }
+            const entryPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryPath);
+            }
+            else if (extensions.some((extension) => entry.name.endsWith(extension))) {
+                found.push(entryPath);
+            }
+        }
+    }
+    await walk(root);
+    return found;
+}
+async function readMany(files) {
+    const contents = new Map();
+    for (const file of files) {
+        contents.set(file, await readIfExists(file));
+    }
+    return contents;
+}
+function filesMatching(contents, patterns) {
+    const matches = [];
+    for (const [file, content] of contents) {
+        if (patterns.some((pattern) => pattern.test(content))) {
+            matches.push(file);
+        }
+    }
+    return matches;
+}
+function containsAny(contents, patterns) {
+    for (const content of contents.values()) {
+        if (patterns.some((pattern) => pattern.test(content))) {
+            return true;
+        }
+    }
+    return false;
+}
+function containsAnyForFiles(contents, files, patterns) {
+    return files.some((file) => {
+        const content = contents.get(file) ?? "";
+        return patterns.some((pattern) => pattern.test(content));
+    });
+}
+function relativeFile(root, file) {
+    return file ? path.relative(root, file) : undefined;
+}