《游戏引擎实现原理》1.1 打包与产物分析

// file: tools/module-graph.mjs
// tier: L1
// verify: node tools/module-graph.mjs
//
// 构建期静态分析：把 src/ 下的 ES 模块扫成一张依赖图。不打包、不跑代码，
// 只解析 import / export 语法，得到每个模块的源字节数、它直接依赖的模块，
// 以及它从每个依赖里「按名字」取了哪些符号。后面 bundle-analyze 与
// split-chunks 都 import 这里的 buildGraph / reachableModules。

import { readdirSync, readFileSync, statSync } from 'node:fs';
import { join, dirname, resolve, relative } from 'node:path';

const IMPORT_RE = /(?:^|\n)\s*(?:import|export)\s+(?:type\s+)?[\s\S]*?\s*from\s*['"]([^'"]+)['"]/g;
const NAMED_IMPORT_RE = /import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g;
const EXPORT_DECL_RE = /^export\s+(?:async\s+)?(?:function|class|const|let|var)\s+([A-Za-z_$][\w$]*)/gm;
const EXPORT_LIST_RE = /^export\s*\{([^}]*)\}/gm;

/** 递归收集 rootDir 下所有非测试 .ts 文件。 */
export function collectModules(rootDir) {
  const out = [];
  const walk = (dir) => {
    for (const name of readdirSync(dir).sort()) {
      const full = join(dir, name);
      if (statSync(full).isDirectory()) walk(full);
      else if (name.endsWith('.ts') && !name.endsWith('.test.ts')) out.push(full);
    }
  };
  walk(rootDir);
  return out;
}

/** 抽出一个模块的静态依赖说明符、导出符号名、以及「从谁取了哪些符号」。 */
export function parseModule(source) {
  const specs = [];
  for (const m of source.matchAll(IMPORT_RE)) {
    const s = m[1];
    if (s.startsWith('.') || s.startsWith('/')) specs.push(s);
  }
  const exports = new Set();
  for (const m of source.matchAll(EXPORT_DECL_RE)) exports.add(m[1]);
  for (const m of source.matchAll(EXPORT_LIST_RE)) {
    for (const part of m[1].split(',')) {
      const name = part.trim().split(/\s+as\s+/).pop().trim();
      if (name) exports.add(name);
    }
  }
  const uses = [];
  for (const m of source.matchAll(NAMED_IMPORT_RE)) {
    const names = [];
    for (const part of m[1].split(',')) {
      const raw = part.trim();
      if (!raw || raw.startsWith('type ')) continue;
      names.push(raw.split(/\s+as\s+/)[0].trim());
    }
    uses.push({ spec: m[2], names });
  }
  return { specs, exports: [...exports], uses };
}

/** 建图：modules 以「相对 cwd 的路径」为键。 */
export function buildGraph(rootDir) {
  const files = collectModules(rootDir);
  const byAbs = new Map(files.map((f) => [resolve(f), relative(process.cwd(), f)]));
  const modules = new Map();
  for (const f of files) {
    const source = readFileSync(f, 'utf8');
    const { specs, exports, uses } = parseModule(source);
    const imports = [];
    const seen = new Set();
    for (const s of specs) {
      const dep = byAbs.get(resolve(dirname(f), s));
      if (dep !== undefined && !seen.has(dep)) {
        seen.add(dep);
        imports.push(dep);
      }
    }
    const deps = [];
    for (const g of uses) {
      const dep = byAbs.get(resolve(dirname(f), g.spec));
      if (dep !== undefined) deps.push({ dep, names: g.names });
    }
    modules.set(byAbs.get(resolve(f)), {
      path: byAbs.get(resolve(f)),
      bytes: Buffer.byteLength(source),
      imports,
      exports,
      uses: deps,
    });
  }
  return { modules };
}

/** 模块级可达集：从 entry 出发静态能到达的所有模块路径（含 entry）。 */
export function reachableModules(graph, entry) {
  const seen = new Set();
  const stack = [entry];
  while (stack.length) {
    const cur = stack.pop();
    if (seen.has(cur)) continue;
    seen.add(cur);
    for (const dep of graph.modules.get(cur)?.imports ?? []) if (!seen.has(dep)) stack.push(dep);
  }
  return seen;
}

/** 一组模块的源字节总和。 */
export function totalBytes(graph, paths) {
  let n = 0;
  for (const p of paths) n += graph.modules.get(p)?.bytes ?? 0;
  return n;
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const graph = buildGraph('src');
  const entry = 'src/apps/glimmer-isle-demo.ts';
  const reach = reachableModules(graph, entry);
  console.log(`模块总数（不含测试）：${graph.modules.size}`);
  console.log(`入口 ${entry} 可达模块：${reach.size}`);
  console.log(`可达源码字节：${totalBytes(graph, reach)}`);
}

模块总数（不含测试）：187
入口 src/apps/glimmer-isle-demo.ts 可达模块：6
可达源码字节：21231

// snippet: tools/bundle-analyze.mjs（节选：拓扑拼接与三段体积）
// tier: L1
// verify: node tools/bundle-analyze.mjs

/** 拓扑序：被依赖者在前（Kahn）；环会让 Kahn 提前停下，剩余按名字补末尾。 */
function topoOrder(graph, paths) {
  const set = new Set(paths);
  const indeg = new Map([...set].map((p) => [p, 0]));
  for (const p of set) {
    for (const dep of graph.modules.get(p)?.imports ?? []) {
      if (set.has(dep)) indeg.set(p, indeg.get(p) + 1);
    }
  }
  const queue = [...set].filter((p) => indeg.get(p) === 0).sort();
  const out = [];
  while (queue.length) {
    const p = queue.shift();
    out.push(p);
    for (const q of set) {
      if (q !== p && (graph.modules.get(q)?.imports ?? []).includes(p)) {
        indeg.set(q, indeg.get(q) - 1);
        if (indeg.get(q) === 0) queue.push(q);
      }
    }
  }
  for (const p of [...set].sort()) if (!out.includes(p)) out.push(p);
  return out;
}

/** 把一组模块按拓扑序拼成一份 bundle 文本（带分隔注释，便于人工核对）。 */
export function bundle(graph, paths) {
  return topoOrder(graph, paths)
    .map((p) => `// ---- ${p} ----\n${stripModuleSyntax(readFileSync(resolve(p), 'utf8')).trim()}`)
    .join('\n\n') + '\n';
}

== 三段体积：源码 / 打包 / 压缩 ==
全图模块数 187  入口可达模块数 6
源码字节  全图 636208  入口可达 21231
bundle字节 全图 627495  入口可达 20842
gzip字节  入口可达 7230
brotli字节 入口可达 6176

== 符号级 tree-shaking ==
保留导出体 11272 字节，删除未被引用导出体 793 字节
删除样例：src/core/kernel.ts#RenderSubsystem, src/core/fixed-step-loop.ts#interpolate, src/core/arena.ts#ScratchArena

写出 artifacts/glimmer.bundle.ts（20842 字节）

$ node artifacts/glimmer.bundle.ts
[glimmer-isle] frames=120 step=0.016666666666666666 speed=2
[glimmer-isle] run A: x=9.71445146547012e-17 z=2.666666666666667 checksum=5142.666666666668
[glimmer-isle] run B: x=9.71445146547012e-17 z=2.666666666666667 checksum=5142.666666666668
[glimmer-isle] deterministic: x=true z=true checksum=true
[glimmer-isle] PASS: 两次运行逐位相同