SpineWallpaper/tools/check-paths.ts

// pnpm check:paths —— 源数据的**孤儿文件**门禁（构建前跑，只看 wallpapers/，不看 dist）。
//
// 与 check:dist 的分工：
//   check:paths  源数据自洽：有没有磁盘上存在、但没有任何 meta.json 声明的资源？
//   check:dist   产物自洽：dist/releases/ 里每个引用是否真的落地、是否越界、JS 语法是否合法。
//
// 为什么单独立这一条：音频文件名**保留中文**（产品要求），而 id 是 build 自增分配的，
// 两者靠 meta.json 的 choices 显式绑定——这正是"地图漏画一格"最容易发生的地方。一个没被声明的 .flac 会安安静静
// 躺在仓库里：类型检查过、构建过、产物自包含，只是那首歌永远选不到，而且没人会发现。
// 依赖删除同理：改动后残留的 `foo-旧版.flac` 会一直跟着构建进分发，白白撑大上传体积。
//
// 用法：node tools/check-paths.ts

import { join, resolve } from "node:path";
import { abs, isDir, log, walkFiles } from "./lib/fs.ts";
import { readVault, VaultError } from "./lib/vault.ts";
import { baseName } from "./lib/generate.ts";

const problems: string[] = [];
let audioChecked = 0;

/** 反查一个目录下的音频文件是否都被 `choices` 认领。 */
async function checkOrphans(opts: {
  dirRel: string;
  choices: { file: string }[];
  where: string;
  /** 音频目录相对声明者所在目录（壁纸就填 "audios"）。 */
  subdir: string;
}): Promise<void> {
  const declared = new Set(opts.choices.map((c) => baseName(c.file)));
  audioChecked += declared.size;
  const dirAbs = abs(join(opts.dirRel, opts.subdir));
  if (!(await isDir(dirAbs))) {
    if (declared.size > 0) problems.push(`${opts.where}: 声明了 ${declared.size} 个音源，但 ${join(opts.dirRel, opts.subdir)} 目录不存在`);
    return;
  }
  for (const name of await walkFiles(dirAbs)) {
    // 允许子目录嵌套：只比较相对路径末段，与实际取用方式一致。
    const leaf = name.split("/").pop() ?? name;
    if (declared.has(leaf)) continue;
    problems.push(
      `${join(opts.dirRel, opts.subdir, name)} 没有被 ${opts.where} 声明——` +
        `它是孤儿文件：既不会被 WE 的 bgm 下拉选中，也不会进任何分发的音频清单。` +
        `删掉它，或者把它加进 meta.json。`,
    );
  }
}

async function main(): Promise<void> {
  const vault = await readVault();

  // 1) 每档壁纸自己的 audios/
  for (const wallpaper of vault.wallpapers) {
    await checkOrphans({
      dirRel: wallpaper.srcRel,
      choices: wallpaper.meta.audio.choices,
      where: `${wallpaper.srcRel}/meta.json`,
      subdir: "audios",
    });
  }

  // 2) 每个游戏的共享音频（wallpapers/<游戏id>/audios/），只被合集分发使用
  for (const game of vault.games) {
    await checkOrphans({
      dirRel: game.srcRel,
      choices: game.meta.audios ?? [],
      where: `${game.srcRel}/meta.json 的 audios`,
      subdir: "audios",
    });
  }

  // 3) 分发级预览图（wallpapers/preview.gif，被所有分发共用）
  if (vault.global.preview !== undefined) {
    const previewRel = join("wallpapers", baseName(vault.global.preview));
    if (await isDir(abs(previewRel))) problems.push(`wallpapers/meta.json 的 preview "${vault.global.preview}" 指向的是一个目录`);
  }

  if (problems.length > 0) {
    log(`check:paths  ✗ ${problems.length} 处问题（已核对 ${audioChecked} 条音源声明）`);
    for (const problem of problems) log(`  ✗ ${problem}`);
    throw new VaultError(`源数据里有 ${problems.length} 处音频声明问题`);
  }
  log(`check:paths  ✓ ${vault.wallpapers.length} 档壁纸 / ${vault.games.length} 个游戏，${audioChecked} 条音源声明无孤儿文件`);
}

// 只在被当作入口直接运行时才自检（被 import 时不该有副作用）。
if (process.argv[1] !== undefined && resolve(process.argv[1]) === abs("tools/check-paths.ts")) {
  await main();
}