5.1 命名规则：前缀/类型/变体/版本

<kind 前缀>_<subject>[_<变体>]_v<NN>

{
  "ruleSet": "naming",
  "specVersion": 1,
  "note": "资产文件名文法：<kind 前缀>_<subject>[_<变体>]_v<NN>。下划线分三段（无变体）或四段（有变体），subject 内的单词用连字符。规则与阈值全部是字符串/整数，Python 与 TS 两侧逐位一致。",
  "kindPrefix": {
    "furniture": "furn",
    "character": "char",
    "ui": "ui",
    "tile": "tile",
    "vfx": "vfx",
    "icon": "icon"
  },
  "variants": ["base", "lit", "dark", "hov", "dis", "alt", "sm", "lg"],
  "subjectPattern": "^[a-z][a-z0-9-]*$",
  "versionPattern": "^v[0-9]{2}$",
  "minFields": 3,
  "maxFields": 4,
  "maxSubjectLen": 24,
  "maxBaseLen": 40
}

#!/usr/bin/env python3
# file: sim/sp05_naming.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/sp05_naming.py
"""命名 lint（S 层）：读资产清单，按 <前缀>_<subject>[_<变体>]_v<NN> 文法逐项检查。
产出 out/sp05_naming.json —— P 层 TS 校验器读它做跨语言对照。规则是字符串/整数，
两侧违例集合逐位一致；违规命名必须真的 fail（负例断言见 core/test/sp05_naming.test.ts）。
"""
import json, os, re, sys

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
ASSETS = os.path.join(ROOT, "config/sp05_assets.json")
RULES = os.path.join(ROOT, "config/sp05_naming_rules.json")
OUT = os.path.join(ROOT, "out")


def lint_one(asset: dict, rules: dict) -> list:
    base = os.path.splitext(os.path.basename(asset["file"]))[0]
    tokens = base.split("_")
    if len(tokens) == rules["minFields"]:
        prefix, subject, version = tokens
        variant = None
    elif len(tokens) == rules["maxFields"]:
        prefix, subject, variant, version = tokens
    else:
        return [{"id": asset["id"], "code": "E_FIELDS", "token": str(len(tokens))}]
    out = []
    if prefix != rules["kindPrefix"].get(asset["kind"], ""):
        out.append({"id": asset["id"], "code": "E_PREFIX", "token": prefix})
    if not re.match(rules["subjectPattern"], subject):
        out.append({"id": asset["id"], "code": "E_CASE", "token": subject})
    if variant is not None and variant not in rules["variants"]:
        out.append({"id": asset["id"], "code": "E_VARIANT", "token": variant})
    if not re.match(rules["versionPattern"], version):
        out.append({"id": asset["id"], "code": "E_VERSION", "token": version})
    return sorted(out, key=lambda v: v["code"])


def main() -> int:
    assets = json.load(open(ASSETS, encoding="utf-8"))["assets"]
    rules = json.load(open(RULES, encoding="utf-8"))
    os.makedirs(OUT, exist_ok=True)
    violations = []
    for a in assets:
        violations.extend(lint_one(a, rules))
    violations.sort(key=lambda v: (v["id"], v["code"]))
    counts = {}
    for v in violations:
        counts[v["code"]] = counts.get(v["code"], 0) + 1
    summary = {"project": "stardust-inn", "ruleSet": rules["ruleSet"],
               "assetCount": len(assets), "violationCount": len(violations),
               "counts": counts, "violations": violations}
    with open(os.path.join(OUT, "sp05_naming.json"), "w", encoding="utf-8") as f:
        json.dump(summary, f, ensure_ascii=False, indent=2, sort_keys=True)
        f.write("\n")
    print(f"assetCount={len(assets)} violations={len(violations)}")
    for code in sorted(counts):
        print(f"  {code}={counts[code]}")
    print("wrote out/sp05_naming.json")
    return 0


if __name__ == "__main__":
    sys.exit(main())

// file: core/src/sp05/naming.ts
// tier: P
// verify: node --test 'core/test/sp05_*.test.ts'
// 命名 lint 的 TS 侧实现：与 sim/sp05_naming.py 共用 config/sp05_naming_rules.json。
// 规则是正则/枚举/整数，故两侧违例集合逐位一致。只允许可擦除 TS 语法。

export type Violation = { id: string; code: string; token: string };
export type Asset = { id: string; kind: string; file: string };
export type NamingRules = { kindPrefix: Record<string, string>; variants: string[];
  subjectPattern: string; versionPattern: string; minFields: number; maxFields: number };

/** 取文件名并去掉最后一个扩展名（对齐 Python os.path.splitext）。 */
export function baseName(path: string): string {
  const file = path.slice(path.lastIndexOf("/") + 1);
  const dot = file.lastIndexOf(".");
  return dot > 0 ? file.slice(0, dot) : file;
}

export function lintNaming(assets: Asset[], rules: NamingRules): Violation[] {
  const out: Violation[] = [];
  for (const a of assets) {
    const t = baseName(a.file).split("_");
    let prefix: string, subject: string, version: string;
    let variant: string | null = null;
    if (t.length === rules.minFields) {
      prefix = t[0]; subject = t[1]; version = t[2];
    } else if (t.length === rules.maxFields) {
      prefix = t[0]; subject = t[1]; variant = t[2]; version = t[3];
    } else {
      out.push({ id: a.id, code: "E_FIELDS", token: String(t.length) });
      continue;
    }
    if (prefix !== (rules.kindPrefix[a.kind] ?? "")) out.push({ id: a.id, code: "E_PREFIX", token: prefix });
    if (!new RegExp(rules.subjectPattern).test(subject)) out.push({ id: a.id, code: "E_CASE", token: subject });
    if (variant !== null && !rules.variants.includes(variant)) out.push({ id: a.id, code: "E_VARIANT", token: variant });
    if (!new RegExp(rules.versionPattern).test(version)) out.push({ id: a.id, code: "E_VERSION", token: version });
  }
  return out.sort((x, y) =>
    x.id < y.id ? -1 : x.id > y.id ? 1 : x.code < y.code ? -1 : x.code > y.code ? 1 : 0);
}

// file: core/test/sp05_naming.test.ts
// tier: P
// verify: node --test 'core/test/sp05_*.test.ts'
// 跨语言对照：读 sim/sp05_naming.py 落盘的 out/sp05_naming.json，断言 TS 侧 lintNaming
// 复算出的违例集合与之一致（整数/字符串类，逐位一致），并带负例断言：违规命名必须真的 fail。
import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { lintNaming, baseName } from "../src/sp05/naming.ts";

const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
const assets = JSON.parse(readFileSync(resolve(ROOT, "config/sp05_assets.json"), "utf8")).assets;
const rules = JSON.parse(readFileSync(resolve(ROOT, "config/sp05_naming_rules.json"), "utf8"));
const py = JSON.parse(readFileSync(resolve(ROOT, "out/sp05_naming.json"), "utf8"));
const key = (v: { id: string; code: string; token: string }): string => `${v.id}:${v.code}:${v.token}`;
const digest = (ls: string[]): string => createHash("sha256").update(ls.join("\n")).digest("hex").slice(0, 16);

test("跨语言：TS 违例集合 == Python 违例集合（逐位一致）", () => {
  const mine = lintNaming(assets, rules).map(key);
  const theirs = (py.violations as { id: string; code: string; token: string }[]).map(key);
  assert.deepEqual(mine, theirs);
  assert.equal(py.assetCount, assets.length);
  assert.equal(digest(mine), digest(theirs));
  console.log(`naming digest = ${digest(mine)}`);
});

test("负例断言：违规命名必须 fail", () => {
  const cases: [string, string, string][] = [
    ["furn_Table-base_v01", "E_CASE", "Table-base"],
    ["furn_lamp_cozy_v01", "E_VARIANT", "cozy"],
    ["ui_button_bg_v01", "E_VARIANT", "bg"],
    ["furn_chair-base_v1", "E_VERSION", "v1"],
    ["furn_plant-pot_v01", "E_PREFIX", "furn"],
    ["ui_panel", "E_FIELDS", "2"],
  ];
  const byId = new Map<string, string[]>();
  for (const v of lintNaming(assets, rules)) byId.set(v.id, [...(byId.get(v.id) ?? []), `${v.code}:${v.token}`]);
  for (const [id, code, token] of cases) {
    assert.ok(byId.get(id)?.includes(`${code}:${token}`), `${id} 应报 ${code}:${token}，实得 ${byId.get(id)}`);
  }
});

test("正例：规范命名一个错都不报；段数错判 E_FIELDS", () => {
  const flagged = new Set(lintNaming(assets, rules).map((v) => v.id));
  for (const id of ["furn_lamp-base_v01", "char_innkeeper-idle_v01", "tile_grass-dark_v01"]) {
    assert.ok(!flagged.has(id), `${id} 不应有违例`);
  }
  assert.equal(baseName("assets/sprites/ui/ui_panel.png"), "ui_panel");
  assert.equal(lintNaming([{ id: "y", kind: "ui", file: "ui_panel_wood_base_v01.png" }], rules)[0].code, "E_FIELDS");
});

assetCount=24 violations=8
  E_CASE=2
  E_FIELDS=1
  E_PREFIX=1
  E_VARIANT=3
  E_VERSION=1