附录 A：视觉规范公式、参数与数据集索引

# 只跑第 7 章的测试（注意引号：让 node 自己展开 glob）
node --test 'core/test/sp07_*.test.ts'
# 跑本卷全部测试
node --test 'core/test/sp*.test.ts'

for f in sim/sp*.py; do /opt/homebrew/bin/python3 "$f" || exit 1; done

#!/usr/bin/env python3
# file: sim/sp17_index.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/sp17_index.py
"""附录 A 的 S 层索引清点器：只登记**本卷 `sp` 前缀**的四个清单（config / sim / core/src /
core/test），按路径排序后逐个登记，算总数并给一个跨语言可复算的摘要（digest）。

只登记**静态文件路径**，不登记产物（out/ 下随时会被清空重建），所以同一份工作区在任何
机器上跑出的清单与摘要都逐位一致；前缀过滤让两卷的数字互不干扰。digest 用两个不同
偏移量的 FNV-1a 32 位拼成 16 位十六进制，TS 侧用 Math.imul 复算，故两侧必然相同。
"""
from __future__ import annotations

import json
import os
import sys

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

GROUPS = (
    ("config", "config", lambda rp: rp.startswith("config/sp")),
    ("sim", "sim", lambda rp: rp.startswith("sim/sp")),
    ("coreSrc", "core/src", lambda rp: rp.startswith("core/src/sp")),
    ("coreTest", "core/test", lambda rp: rp.startswith("core/test/sp")),
)


def listing(rel: str, pred) -> list[str]:
    d = os.path.join(ROOT, rel)
    out: list[str] = []
    for dirpath, _dirs, files in os.walk(d):
        for n in files:
            rp = os.path.relpath(os.path.join(dirpath, n), ROOT)
            if pred(rp):
                out.append(rp)
    return sorted(out)


def fnv1a(text: str, basis: int) -> int:
    h = basis
    for ch in text.encode("utf-8"):
        h = ((h ^ ch) * 0x01000193) & 0xFFFFFFFF
    return h


def digest_of(lines: list[str]) -> str:
    joined = "\n".join(lines)
    return f"{fnv1a(joined, 0x811C9DC5):08x}{fnv1a(joined, 0x7FFFFFFF):08x}"


def main() -> int:
    groups: dict[str, list[str]] = {}
    all_lines: list[str] = []
    for key, rel, pred in GROUPS:
        files = listing(rel, pred)
        groups[key] = files
        all_lines.extend(files)

    spec = json.load(open(os.path.join(ROOT, "config/visual_spec.json"), encoding="utf-8"))
    report = {
        "project": spec["project"],
        "counts": {k: len(v) for k, v in groups.items()},
        "total": len(all_lines),
        "digest": digest_of(all_lines),
        "groups": groups,
    }
    with open(os.path.join(ROOT, "out/sp17_index.json"), "w", encoding="utf-8") as f:
        json.dump(report, f, ensure_ascii=False, indent=2)
        f.write("\n")

    print(f"project={report['project']} total={report['total']} digest={report['digest']}")
    for k, _rel, _pred in GROUPS:
        print(f"  {k:<9} {report['counts'][k]:>3}")
    print("wrote out/sp17_index.json")
    return 0


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

project=stardust-inn total=197 digest=49f80669b540365b
  config     50
  sim        51
  coreSrc    48
  coreTest   48
wrote out/sp17_index.json

// file: core/src/sp17/index.ts
// tier: P
// verify: node --test 'core/test/sp17_*.test.ts'
// 附录 A 的 P 层索引内核。与 sim/sp17_index.py 同一套规则：只登记本卷 `sp` 前缀的四个
// 清单，按路径排序后拼接，用两个不同偏移量的 FNV-1a 32 位拼成 16 位十六进制摘要。
// 只登记静态文件路径，不登记产物，故两侧清单与摘要必然逐位一致。只允许可擦除 TS 语法。

import { readdirSync, statSync } from "node:fs";
import { join, relative, sep } from "node:path";

const GROUPS: { key: string; rel: string; pred: (rp: string) => boolean }[] = [
  { key: "config", rel: "config", pred: (rp) => rp.startsWith("config/sp") },
  { key: "sim", rel: "sim", pred: (rp) => rp.startsWith("sim/sp") },
  { key: "coreSrc", rel: "core/src", pred: (rp) => rp.startsWith("core/src/sp") },
  { key: "coreTest", rel: "core/test", pred: (rp) => rp.startsWith("core/test/sp") },
];

export function listing(root: string, rel: string, pred: (rp: string) => boolean): string[] {
  const out: string[] = [];
  const walk = (abs: string) => {
    for (const name of readdirSync(abs)) {
      const full = join(abs, name);
      const rp = relative(root, full).split(sep).join("/");
      if (statSync(full).isDirectory()) walk(full);
      else if (pred(rp)) out.push(rp);
    }
  };
  walk(join(root, rel));
  return out.sort();
}

export function fnv1a(text: string, basis: number): number {
  let h = basis >>> 0;
  const bytes = Buffer.from(text, "utf8");
  for (const b of bytes) h = Math.imul(h ^ b, 0x01000193) >>> 0;
  return h;
}

export function digestOf(lines: string[]): string {
  const joined = lines.join("\n");
  const a = fnv1a(joined, 0x811c9dc5).toString(16).padStart(8, "0");
  const b = fnv1a(joined, 0x7fffffff).toString(16).padStart(8, "0");
  return a + b;
}

export function indexWorkspace(root: string): { counts: Record<string, number>; total: number; digest: string; groups: Record<string, string[]> } {
  const groups: Record<string, string[]> = {};
  const counts: Record<string, number> = {};
  const all: string[] = [];
  for (const g of GROUPS) {
    const files = listing(root, g.rel, g.pred);
    groups[g.key] = files;
    counts[g.key] = files.length;
    all.push(...files);
  }
  return { counts, total: all.length, digest: digestOf(all), groups };
}

✔ 索引清点：TS 复算与 Python 产物逐位一致 (18.670875ms)
✔ 正例：四个清单都非空，且 total 等于四者之和 (15.245083ms)
✔ 负例：摘要内容敏感，改一个字符必须换一个摘要 (0.115667ms)
✔ 负例：空清单有确定摘要，且与单元素清单不同 (0.072708ms)
ℹ tests 4
ℹ pass 4
ℹ fail 0