核心能力验证

1. ktlint 能力边界

1.1 工具概述

ktlint 是 Pinterest 开源的 Kotlin 代码格式化和 lint 工具，设计哲学是「零配置」——遵循官方 Kotlin 代码规范，无需繁琐的 XML/YAML 配置。

关键数据：

• GitHub Stars：6,674（截至 2026-04）
• 最新版本：1.8.0（2025-11 发布）
• 独立可执行文件：约 45MB
• 启动时间：0.5-1 秒

1.2 沙盒友好性验证

独立运行能力

ktlint 提供原生 CLI，无需 Gradle 或 Maven：

# 安装（单命令）
curl -sSLO https://github.com/pinterest/ktlint/releases/download/1.8.0/ktlint
chmod +x ktlint

# 基础使用（无需配置文件）
./ktlint                    # 检查当前目录所有 .kt/.kts 文件
./ktlint --format          # 自动修复可修复的问题
./ktlint --stdin           # 从标准输入读取代码（沙盒关键特性）

沙盒关键特性：--stdin 模式允许直接从内存分析代码，无需文件系统：

# 沙盒场景：分析单个文件内容
echo 'fun main() { println("Hello") }' | ./ktlint --stdin

# 结合 --stdin-path 保持文件上下文
cat MyComposable.kt | ./ktlint --stdin --stdin-path MyComposable.kt

内存与性能基准

结论：ktlint 完全满足沙盒环境的资源约束（< 512MB 内存，< 5 秒响应）。

1.3 Compose 规则支持度

ktlint 专注于代码风格，不包含 Compose 语义规则：

弥补方案：通过 .editorconfig 定制 Kotlin/Compose 特定规则：

# .editorconfig
[*.{kt,kts}]
# 标准 Kotlin 风格
indent_size = 4
max_line_length = 120

# Compose 特定：允许大写函数名（@Composable）
ktlint_function_naming_ignore_when_annotated_with = Composable

# Compose 特定：禁用通配符导入（避免 Composable 命名冲突）
ktlint_no-wildcard-imports = true

1.4 自动修复能力

ktlint 的 --format（或 -F）标志支持自动修复大部分风格问题：

# 自动修复当前目录所有问题
./ktlint -F

# 仅修复特定文件
./ktlint -F src/ui/components/*.kt

# 修复并输出到 stdout（沙盒场景）
./ktlint --stdin -F < input.kt > output.kt

自动修复覆盖率：

• 可自动修复的规则：约 60%（主要是格式相关）
• 需手动修复的规则：命名违规、复杂结构问题

2. Android Lint 独立模式验证

2.1 工具定位

Android Lint 是 Google 官方提供的 Android 专项静态分析工具，专为 Android 项目设计，包含 200+ 条 Android 特定规则，其中 20+ 条专门针对 Jetpack Compose。

关键数据：

• 随 Android SDK 分发
• 最新版本：8.2+（绑定 AGP 8.2）
• 独立 CLI 路径：$ANDROID_SDK/cmdline-tools/latest/bin/lint

2.2 沙盒适配挑战

挑战 1：Gradle 项目检测

Android Lint 会主动检测项目类型，对 Gradle 项目强制要求使用 Gradle Wrapper：

$ lint app/src/

app/build.gradle: Error: "app" is a Gradle project. 
To correctly analyze Gradle projects, you should run "gradlew :lint" instead.

影响：无法在沙盒中直接对 Gradle 项目使用独立 lint CLI。

挑战 2：SDK 依赖

即使绕过 Gradle 检测，Android Lint 仍需：

• Android SDK（~500MB）
• 项目依赖的编译类路径
• lint.xml 配置文件的完整解析

资源需求：

2.3 可行方案：非 Gradle 项目模式

Android Lint 支持分析非 Gradle 项目，需手动指定源码和资源：

# 手动指定项目结构（绕过 Gradle）
lint \
  --sources src/main/kotlin \
  --resources src/main/res \
  --classpath libs/androidx-compose-runtime.jar \
  --sdk-home /opt/android-sdk \
  my-project/

局限性：

• 需手动维护依赖类路径（Compose 库、Kotlin 标准库等）
• 无法解析 Gradle 的动态依赖
• 配置复杂度与项目规模成正比

2.4 Compose 专项规则清单

Android Lint 提供的 Compose 特定规则（共 23 条）：

结论：如需完整的 Compose 规则支持，必须使用 Android Lint，但需接受 Gradle 依赖或复杂的 CLI 配置。

3. Detekt 深度分析

3.1 工具概述

Detekt 是专为 Kotlin 设计的静态代码分析工具，基于 Kotlin 编译器提供的 PSI（Program Structure Interface），支持代码异味检测、复杂度分析和自定义规则。

关键数据：

• GitHub Stars：6,892（截至 2026-04）
• 最新版本：1.23.8（稳定版）、2.0.0-alpha.2（开发版）
• CLI 大小：~60MB（含所有依赖）
• 内置规则：200+ 条

3.2 沙盒适配能力

独立 CLI 运行

Detekt 提供完整的 CLI 支持：

# 下载 CLI
curl -sSLO https://github.com/detekt/detekt/releases/download/v1.23.8/detekt-cli-1.23.8.zip
unzip detekt-cli-1.23.8.zip

# 基础使用
./detekt-cli-1.23.8/bin/detekt-cli \
  --input src/ \
  --config detekt.yml \
  --report html:report.html

# 仅分析特定文件（沙盒场景）
./detekt-cli --input src/ui/components/LoginScreen.kt

分析模式选择

Detekt 1.23.8+ 引入 --analysis-mode 参数，适应不同资源环境：

沙盒推荐配置：

# detekt.yml（沙盒优化版）
build:
  # 使用轻量分析模式
  analysisMode: light

# 禁用需要类型解析的规则
rules:
  potential-bugs:
    # 这些规则需要 full 模式
    UnsafeCallOnNullableType:
      active: false
    UnsafeCast:
      active: false

3.3 Compose 支持方案

方案 A：Twitter Compose Rules（推荐）

Twitter 开源的 Detekt 插件，提供 15+ 条 Compose 特定规则：

// build.gradle（沙盒环境外准备）
dependencies {
    detektPlugins("com.twitter.compose.rules:detekt:0.0.26")
}

支持的 Compose 规则示例：

方案 B：自定义规则

Detekt 支持自定义规则，可自建 Compose 检测：

class ComposeRememberRule(config: Config) : Rule(config) {
    override val issue = Issue(
        id = "ComposeRememberCheck",
        severity = Severity.Defect,
        description = "Ensure expensive computations are wrapped in remember",
        debt = Debt.FIVE_MINS
    )

    override fun visitCallExpression(expression: KtCallExpression) {
        super.visitCallExpression(expression)
        
        // 检测在 Composable 中调用非 remember 的昂贵计算
        if (expression.isInComposableContext() && 
            expression.isExpensiveCall() &&
            !expression.isWrappedInRemember()) {
            
            report(CodeSmell(issue, Entity.from(expression), 
                "Expensive call should be wrapped in remember{}"))
        }
    }
}

3.4 与 ktlint 的集成

Detekt 内置 ktlint 规则集（formatting 规则集），可替代独立 ktlint：

# detekt.yml
formatting:
  active: true
  # 继承 ktlint 的所有规则
  indent:
    active: true
    indentSize: 4
  finalNewline:
    active: true

但推荐方案：独立使用 ktlint + Detekt，原因：

• ktlint 的 --format 自动修复更可靠
• ktlint 的 --stdin 模式更适合沙盒实时分析
• 分离关注点：ktlint 负责格式，Detekt 负责质量

4. 编译依赖分析

4.1 类型解析的依赖链

高级静态分析（如空安全检测）需要「类型解析」，这依赖以下组件：

flowchart TD
    A[类型解析] --> B[Kotlin 编译器]
    B --> C[依赖类路径]
    C --> D[Compose 库]
    C --> E[Kotlin 标准库]
    C --> F[项目依赖]
    F --> G[Maven/Gradle 解析]
    
    style A fill:#ffcdd2
    style G fill:#ffcdd2

4.2 沙盒环境下的妥协方案

4.3 预编译依赖缓存策略

若需在沙盒支持类型解析，可采用「预编译依赖」策略：

# Dockerfile：预下载常用依赖
FROM openjdk:17-alpine

# 预下载 Kotlin 标准库和 Compose 核心库
RUN mkdir -p /opt/classpath && \
    cd /opt/classpath && \
    # Kotlin 标准库
    wget https://repo1.maven.org/maven2/org/jetbrains/kotlin/kotlin-stdlib/1.9.22/kotlin-stdlib-1.9.22.jar && \
    # Compose Runtime
    wget https://repo1.maven.org/maven2/androidx/compose/runtime/runtime/1.6.0/runtime-1.6.0.jar && \
    # Compose UI
    wget https://repo1.maven.org/maven2/androidx/compose/ui/ui/1.6.0/ui-1.6.0.jar

ENV DETEKT_CLASSPATH=/opt/classpath/*

效果：将依赖下载从运行时移至镜像构建时，沙盒启动时无需网络。

本章节验证了三大核心工具在沙盒环境中的能力边界，为后续方案设计提供了数据支撑。