STBaseProject/.swiftlint.yml at main · i-stack/STBaseProject · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
# SwiftLint 配置 —— STBaseProject
# 与 .github/check_try_question_mark.sh 互补：try? 政策由专门脚本兜底，本文件聚焦
# 其他反模式：强解包、as!、过长文件、含糊 Bool 参数、`@objc` 滥用等。
#
# 渐进式落地策略：
# - 严重项标 error（as!、Markdown 外 try! 在源码区）
# - 风格项标 warning，先看清存量数量再考虑收紧
# - 大量历史代码可以通过 `disabled_rules` 精确豁免

included:
  - Sources

# SwiftLint analyze 的 unused_import 对系统框架 import（Foundation/UIKit/Security 等）存在已知误报：
# swiftc 编译日志 0 条 unused import 警告，删除这些 import 会导致编译失败
# （如 STSecurityModels 依赖 Foundation 的 Date/TimeInterval，见 .github/workflows/swift.yml 的 Analyze 步骤）。
# 该规则已整体禁用（见下方 analyzer_rules），故无需在此按文件排除。
excluded:
  - Sources/STMarkdown/Resources
  - .build
  - DerivedData

# 默认规则中需要关闭或软化的
disabled_rules:
  - todo                          # TODO/FIXME 不视为告警
  - identifier_name               # 历史命名以 st_ / ST 前缀为主，先不卡
  - type_name                     # 同上
  - trailing_whitespace           # 历史空白多，独立 PR 清理
  - opening_brace                 # 与历史风格不一致
  # 注意：line_length 是默认开启规则，不在 disabled_rules 中关闭，
  # 直接在下方 line_length: 配置块生效（置于 disabled_rules 会导致同名配置块被忽略）
  - force_try                     # 由 st_no_force_try_outside_markdown 精准限制，允许 STMarkdown 静态正则
  - notification_center_detachment # 生命周期中主动解绑是计时器/HUD的既有行为，不能限定在 deinit
  - missing_docs                   # 存量 882 个公开 API 缺文档，暂不纳入 --strict 门槛；文档补齐专项后再恢复 opt_in_rules

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
  - redundant_objc_attribute       # ★ 检查不必要的 @objc，与顶部注释“@objc 滥用”策略一致
  - fallthrough
  - fatal_error_message
  - flatmap_over_map_reduce
  - joined_default_parameter
  - literal_expression_end_indentation
  - lower_acl_than_parent         # ★ 子声明可见性高于父类型时报警
  - modifier_order
  - operator_usage_whitespace
  - redundant_string_enum_value
  - sorted_imports
  - toggle_bool
  - computed_accessors_order
  # === 公共基础库 Bug Prevention（第一批，低风险高价值）===
  - weak_delegate                    # ★ delegate 必须为 weak，否则循环引用
  - discarded_notification_center_observer  # ★ block observer token 应被持有，便于按生命周期移除
  - unhandled_throwing_task          # ★ 显式处理 throwing Task 的错误或结果
  # 注：SwiftLint 无“公开类强制 final”规则（final_class 不存在）；如需约束可改用
  # 架构评审/PR 模板，或 static_over_final_class（语义不同，未启用）。

force_cast: error                 # as! 直接 error

analyzer_rules:
  # 本仓库是底层公用库：大量 public/internal/fileprivate API 提供给宿主 App / Example 模块调用，
  # SwiftLint analyze 的 analyzer_rules 只扫描包内 99 个文件，看不到外部调用方，
  # 会系统性误报 unused_import 与 unused_declaration（且 swiftc 编译日志证明 import 必需）。
  # 验证依据见下。故整体禁用这两个 analyzer 规则。
  # - unused_import  : 系统框架 import（Foundation/UIKit/Security 等）被误判为冗余，
  #                    clean build 的 swiftc 编译日志 unused import 警告为 0 条，删除会导致编译失败。
  # - unused_declaration: 对外暴露的库 API 在包内无引用，被误判为未使用。
  # - unused_import
  # - unused_declaration

# 公开 API 文档缺失检查：存量 882 个未清零，暂移出 opt_in_rules（见 disabled_rules），
# 待文档补齐专项后再恢复并重新纳入 --strict 门槛。仅检查 public 级别。
# 恢复方式：从 disabled_rules 移回 opt_in_rules，并重新启用下方配置块：
# missing_docs:
#   warning: public

# === 规则参数化 ===
line_length:
  warning: 300
  error: 400
  ignores_urls: true
  ignores_function_declarations: true
  ignores_comments: true

function_body_length:
  warning: 120
  error: 250

type_body_length:
  warning: 750
  error: 1000

file_length:
  warning: 1200
  error: 2500
  ignore_comment_only_lines: true

cyclomatic_complexity:
  warning: 22
  error: 30

function_parameter_count:
  warning: 8
  error: 9
  ignores_default_parameters: true

large_tuple:
  warning: 3
  error: 4

nesting:
  type_level:
    warning: 3
  function_level:
    warning: 2

# === 自定义规则 ===
custom_rules:
  st_no_swiftlint_disable:
    name: "SwiftLint disable comments are forbidden"
    regex: 'swiftlint\s*:\s*disable(?:\s|:|$)'
    match_kinds:
      - comment
    message: "禁止使用 swiftlint:disable 规避规则；请修复真实问题或调整项目级规则配置。"
    severity: error

  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)(?:Swift\.)?print\s*\('
    message: "请使用 STLog(...) 输出日志，避免 print 在生产环境泄露。"
    severity: warning
    excluded:
      - "Sources/STUIKit/STLog/.*"          # 日志模块自身
      - "Sources/STMarkdown/Resources/.*"
      - "Sources/STNetwork/STWebSocket.swift"   # DEBUG-only 日志封装层，等同 STLog 豁免

reporter: "xcode"