Miooowo.STS2RitsuLib.ModAnalyzers 0.0.1

Miooowo.STS2RitsuLib.ModAnalyzers

English

面向 Slay the Spire 2 / RitsuLib mod 的 Roslyn analyzer。

安装

在 mod 项目中引用 analyzer 包：

<PackageReference Include="Miooowo.STS2RitsuLib.ModAnalyzers" Version="0.0.1" PrivateAssets="all" />

包会通过 buildTransitive 自动收集常见文件。如果你关闭了自动收集，也可以手动把本地化 JSON 暴露给 analyzer：

<AdditionalFiles Include="MyMod/localization/**/*.json" />

支持的本地化文件结构：

localization/eng/cards.json          # 游戏 LocTable
localization/zhs/cards.json
localization/eng/card_keywords.json
localization/eng.json                # RitsuLib I18N（单段布局）
localization/zhs.json
localization/settings/eng.json       # RitsuLib I18N 桥接特性子目录

路径分流规则（与 I18N.NormalizeLanguageCode 对齐）：

• localization/<lang>/<table>.json — 首段是已知语言码（eng / zhs / jpn / kor / deu / esp / fra / ita / pol / ptb / rus / tha / tur 及别名）→ 游戏 LocTable。
• localization/<lang>.json — 单段且文件名是已知语言码 → I18N 文件。
• localization/<feature>/<lang>.json（或更深） — 首段不是语言码、文件名是 → I18N 桥接特性目录（pckFolders 风格）。

语言集合从 localization/ 下的目录识别；即使语言目录没有 JSON 文件也会参与 RITSU001 检查。

诊断

RITSU001 会检查：

• owned keyword 注册，包括自定义 keyword table/key
• card pile 与 top-bar button 的 static_hover_tips
• RitsuLib 内容模型本地化键，例如 cards、powers、relics、characters、ancients
• 传给 I18N.Get、I18N.TryGet、I18N.ContainsKey 的常量 key
• Ancient 对话键（4 变体 any-of：0-0.ancient / 0-0r.ancient / 0-0.char / 0-0r.char 任一存在即满足）
• ModSettings 属性中的 *LocKey / *Key 参数
• WithSharedTooltip / WithTooltip 动态变量提示

RITSU001 只会跟踪已识别的 RitsuLib API 调用；同名普通方法（例如 ModelDb.Power<T>() 或项目内自定义 helper）不会触发本地化诊断。

RITSU001 按 key 单独判断严重级别：eng 缺失但任一非 eng 语言已存在该 key 时为 Warning，否则为 Error；非 eng 语言缺失且 eng 也缺失为 Error，eng 已存在时为 Warning。同一 JSON 内混合 Error / Warning 时会拆成多条诊断。

RITSU002（Ancient 对话 r 混用）只针对 ancients.json 做结构性检查。按 <base>{idx}- 分组聚合 key，组内若同时存在带 r 与不带 r 的行 → 每语言每段一条 Warning。.sfx、.next、-attack、-visit 等附加 key 不计入分组。

RITSU003（未知表名）只是 Info 级。已知表白名单：

cards, relics, potions, powers, characters, events, ancients,
encounters, acts, monsters, orbs, enchantments, afflictions,
card_keywords, static_hover_tips, epochs, achievements, stories

如果维护自定义表，可在对应文件加 // #pragma warning disable RITSU003 抑制。

自动 AdditionalFiles

这个包会通过 buildTransitive 默认把以下文件送进 analyzer：

• mod_manifest.json
• **/localization/**/*.json
• *.tscn、*.tres、*.theme.json、*.guids.txt
• 常见资源扩展名，如 png、ogg、bank、gdshader

可以在项目里关闭：

<PropertyGroup>
  <RitsuLibAnalyzersAutoAdditionalFiles>false</RitsuLibAnalyzersAutoAdditionalFiles>
  <RitsuLibAnalyzersIncludeAssets>false</RitsuLibAnalyzersIncludeAssets>
  <RitsuLibAnalyzersIncludeGodotTextResources>false</RitsuLibAnalyzersIncludeGodotTextResources>
</PropertyGroup>

Rider 快速修复

Rider 可以加载 NuGet 包中的 Roslyn analyzer、completion provider 和 code fix。启用 Roslyn analyzers 后，把光标放在诊断高亮位置并按 Alt+Enter。

Rider 2025.2+ 中，在 RitsuLib 资源路径参数或 AssetProfile 路径里输入 res://， 会补全项目实际资源根、目录、文件，以及常用的 images/relics、images/cards、 images/characters 和 images/keywords 路径模板。若项目里存在可静态解析的 ResPath / ResourceRoot 等静态字符串，也会在插值字符串中提示该符号。

可用修复：

• 添加缺失的本地化到 <language>/<table>.json（RITSU001）— 只追加当前诊断对应 JSON 的缺失 key，值为 ""；目标文件不存在时自动创建。
• 修复所有本地化缺失问题（RITSU001）— 收集当前项目所有 RITSU001，并一次性创建/更新所有语言、所有目标 JSON。
• 插入本地化 JSON 片段（RITSU001）— 在诊断位置附近插入注释形式的 JSON，方便手动复制。
• 添加 res:// 前缀（RITSU013）— 自动补全资源路径前缀；能唯一匹配项目资源时会补齐实际资源根，并优先复用项目内唯一的资源根符号。
• 插入 RitsuLib TODO 修复片段（兜底）

此外，对 RitsuLib 已标记 [Obsolete] 的 API 调用（编译器 CS0618），Rider 会额外提供迁移修复：

本地开发

测试本地构建包时，Pack 会默认覆盖安装同版本包到本机 NuGet 全局包缓存。

构建、打包并覆盖安装：

dotnet test C:\Users\Lenovo\Desktop\STS2RitsuLibModAnalyzers\RitsuLibModAnalyzers.sln --no-restore
dotnet msbuild C:\Users\Lenovo\Desktop\STS2RitsuLibModAnalyzers\RitsuLibModAnalyzer\STS2RitsuLib.ModAnalyzers.csproj /t:Pack /p:Configuration=Release

默认安装路径为 %USERPROFILE%\.nuget\packages，也会尊重 NUGET_PACKAGES 环境变量。可以用 /p:NuGetGlobalPackagesFolder=... 覆盖目标目录；用 /p:InstallAnalyzerOnPack=false 只打包不安装。