Add SwiftLint to CI workflow and enhance error handling in STBaseModel and STHUD

i-stack · i-stack · commit 3e9fe1366a52 · 2026-05-07T17:34:36.000+08:00
diff --git a/.github/workflows/swift.yml b/.github/workflows/swift.yml
@@ -18,6 +18,15 @@ jobs:
     - uses: actions/checkout@v4
     - name: Check try? policy
       run: bash .github/check_try_question_mark.sh
+    - name: SwiftLint
+      run: |
+        if ! command -v swiftlint >/dev/null 2>&1; then
+          brew install swiftlint
+        fi
+        swiftlint version
+        # 不加 --strict：warning 不阻断 CI，仅 .swiftlint.yml 中明确为 error 级别的规则会失败构建。
+        # 待存量 warning 清零后可改为 --strict 提升门槛。
+        swiftlint --reporter github-actions-logging
     - name: Build
       run: xcodebuild -scheme STBaseProject-Package -destination 'generic/platform=iOS Simulator' build
     - name: Build For Testing
diff --git a/.swiftlint.yml b/.swiftlint.yml
@@ -0,0 +1,128 @@
+# SwiftLint 配置 —— STBaseProject
+# 与 .github/check_try_question_mark.sh 互补：try? 政策由专门脚本兜底，本文件聚焦
+# 其他反模式：强解包、as!、过长文件、Bool 旗参痕迹、`@objc` 滥用等。
+#
+# 渐进式落地策略：
+# - 严重项标 error（as!、Markdown 外 try! 在源码区）
+# - 风格项标 warning，先看清存量数量再考虑收紧
+# - 大量历史代码可以通过 `disabled_rules` 精确豁免
+
+included:
+  - Sources
+
+excluded:
+  - Sources/STMarkdown/Resources
+  - .build
+  - DerivedData
+
+# 默认规则中需要关闭或软化的
+disabled_rules:
+  - todo                          # TODO/FIXME 不视为告警
+  - identifier_name               # 历史命名以 st_ / ST 前缀为主，先不卡
+  - type_name                     # 同上
+  - trailing_whitespace           # 历史空白多，独立 PR 清理
+  - opening_brace                 # 与历史风格不一致
+  - line_length                   # 由下方自定义长度覆盖
+  - force_try                     # 由 st_no_force_try_outside_markdown 精准限制，允许 STMarkdown 静态正则
+
+opt_in_rules:
+  - empty_count
+  - empty_string
+  - explicit_init
+  - first_where
+  - last_where
+  - redundant_nil_coalescing
+  - redundant_type_annotation
+  - sorted_first_last
+  - prohibited_super_call
+  - overridden_super_call
+  - closure_end_indentation
+  - closure_spacing
+  - contains_over_filter_count
+  - contains_over_first_not_nil
+  - convenience_type
+  - discouraged_optional_boolean  # ★ 标记 Optional<Bool>，常是 Bool 旗参的延伸坏味
+  - fallthrough
+  - fatal_error_message
+  - flatmap_over_map_reduce
+  - force_unwrapping              # ★ 强解包警告（不直接 error，避免一次性失血）
+  - implicitly_unwrapped_optional # ★ 隐式解包变量
+  - joined_default_parameter
+  - literal_expression_end_indentation
+  - lower_acl_than_parent         # ★ 子声明可见性高于父类型时报警
+  - modifier_order
+  - operator_usage_whitespace
+  - redundant_string_enum_value
+  - sorted_imports
+  - toggle_bool
+
+force_cast: error                 # as! 直接 error
+
+analyzer_rules:
+  - unused_import
+  - unused_declaration
+
+# === 规则参数化 ===
+line_length:
+  warning: 220
+  error: 300
+  ignores_urls: true
+  ignores_function_declarations: true
+  ignores_comments: true
+
+function_body_length:
+  warning: 120
+  error: 250
+
+type_body_length:
+  warning: 600
+  error: 1000
+
+file_length:
+  warning: 1200
+  error: 2500
+  ignore_comment_only_lines: true
+
+cyclomatic_complexity:
+  warning: 15
+  error: 30
+
+nesting:
+  type_level: 3
+
+# === 自定义规则 ===
+custom_rules:
+  st_no_force_try_outside_markdown:
+    name: "try! outside STMarkdown is forbidden"
+    regex: '\\btry!'
+    match_kinds:
+      - keyword
+    message: "try! 仅在 STMarkdown 静态正则编译路径允许，其它位置请使用 do/catch。"
+    severity: error
+    excluded:
+      - "Sources/STMarkdown/.*"
+
+  st_no_print:
+    name: "Use STLog instead of print"
+    regex: '(?<![\w.])print\('
+    message: "请使用 STLog(...) 输出日志，避免 print 在生产环境泄露。"
+    severity: warning
+    excluded:
+      - "Sources/STUIKit/STLog/.*"          # 日志模块自身
+      - "Sources/STMarkdown/Resources/.*"
+
+  st_avoid_bool_flag_param:
+    name: "Avoid trailing Bool parameters (use enum)"
+    regex: '\bfunc\s+\w+\([^)]*\b(enabled|disabled|isEnabled|on|off|flag)\s*:\s*Bool\s*\)'
+    message: "Bool 旗参可读性差，建议改为枚举（如 case enabled / disabled）。"
+    severity: warning
+
+  st_chinese_only_doc:
+    name: "Public doc should include English"
+    regex: '^\s*///\s*[一-鿿]+[^/]*$\n^(?!\s*///)'
+    message: "公共 API 文档建议提供英文版本（中文可保留作为辅助说明）。"
+    severity: warning
+    excluded:
+      - "Sources/STLocalizable/.*"
+
+reporter: "xcode"
diff --git a/Sources/STBaseModel/STBaseModel.swift b/Sources/STBaseModel/STBaseModel.swift
@@ -594,7 +594,11 @@ open class STBaseModel: NSObject {
             // 同上，必须早于 [String: Any] 分支。
             let copy = NSMutableDictionary(capacity: mutableDict.count)
             for (k, v) in mutableDict {
-                copy.setObject(st_deepCopy(value: v), forKey: k as! NSCopying)
+                guard let key = k as? NSCopying else {
+                    assertionFailure("NSMutableDictionary key does not conform to NSCopying.")
+                    continue
+                }
+                copy.setObject(st_deepCopy(value: v), forKey: key)
             }
             return copy
         case let array as [Any]:
diff --git a/Sources/STHUD/STHUD.swift b/Sources/STHUD/STHUD.swift
@@ -32,6 +32,13 @@ public enum STHUDType {
     case text         // 纯文本 Toast（无图标，自动隐藏）
 }
 
+// MARK: - HUD 阴影开关
+/// Shadow toggle for HUD theme. Prefer this over the legacy `Bool` setter for clearer call-sites.
+public enum STHUDShadow: Equatable {
+    case enabled
+    case disabled
+}
+
 // MARK: - HUD 主题配置
 public struct STHUDTheme {
     public var backgroundColor: UIColor
@@ -51,6 +58,12 @@ public struct STHUDTheme {
     public var labelFont: UIFont?
     public var detailLabelFont: UIFont?
 
+    /// 类型化阴影开关。底层仍用 Bool 存储，便于现有持久化/编码兼容。
+    public var shadow: STHUDShadow {
+        get { self.shadowEnabled ? .enabled : .disabled }
+        set { self.shadowEnabled = (newValue == .enabled) }
+    }
+
     public init(backgroundColor: UIColor = UIColor.black.withAlphaComponent(0.8),
                 textColor: UIColor = .white,
                 detailTextColor: UIColor = .lightGray,
@@ -191,10 +204,18 @@ public class STHUD: NSObject {
 
     /// 设置阴影
     /// - Parameter enabled: 是否启用阴影
+    @available(*, deprecated, message: "Use setShadow(_:) with STHUDShadow for clearer call-sites.")
+    // swiftlint:disable:next st_avoid_bool_flag_param
     public func setShadowEnabled(_ enabled: Bool) {
         self.theme.shadowEnabled = enabled
     }
 
+    /// 设置阴影（类型化 API）。
+    /// - Parameter shadow: `.enabled` 启用阴影；`.disabled` 关闭。
+    public func setShadow(_ shadow: STHUDShadow) {
+        self.theme.shadow = shadow
+    }
+
     /// 设置成功图标
     /// - Parameter iconName: 图标名称
     public func setSuccessIcon(_ iconName: String?) {
diff --git a/Sources/STMarkdown/Table/STMarkdownTableView.swift b/Sources/STMarkdown/Table/STMarkdownTableView.swift
@@ -174,7 +174,10 @@ extension STMarkdownTableView: UICollectionViewDataSource {
         let cell = collectionView.dequeueReusableCell(
             withReuseIdentifier: STMarkdownTableCell.reuseIdentifier,
             for: indexPath
-        ) as! STMarkdownTableCell
+        )
+        guard let cell = cell as? STMarkdownTableCell else {
+            return cell
+        }
 
         if let tableData,
            indexPath.section < tableData.cells.count,
diff --git a/Sources/STUIKit/STLog/STLogView.swift b/Sources/STUIKit/STLog/STLogView.swift
@@ -425,7 +425,12 @@ extension STLogView: UITableViewDataSource, UITableViewDelegate {
     }
 
     public func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
-        let cell = tableView.dequeueReusableCell(withIdentifier: "STLogTableViewCell", for: indexPath) as! STLogTableViewCell
+        guard let cell = tableView.dequeueReusableCell(
+            withIdentifier: "STLogTableViewCell",
+            for: indexPath
+        ) as? STLogTableViewCell else {
+            return UITableViewCell(style: .subtitle, reuseIdentifier: nil)
+        }
         guard indexPath.row < self.displayedLogEntries.count else { return cell }
         cell.configure(with: self.displayedLogEntries[indexPath.row])
         return cell
