《游戏引擎实现原理》5.1 模块边界与依赖方向

// file: src/core/module-graph.ts
// tier: L1
// verify: npx vitest run src/core/module-graph.test.ts
//
// helio 内核：模块依赖图。把「谁 import 谁」抽象成有向图，
// 提供两件纯函数：找向上依赖、找循环依赖。文件系统遍历交给 CLI 工具。

export const LAYER_INDEX = {
  Platform: 0,
  Kernel: 1,
  Render: 2,
  Subsystem: 3,
  Game: 4,
} as const;

export type LayerName = keyof typeof LAYER_INDEX;

/** 目录名 -> 层。未列出的目录一律当 Kernel（内核是最底、最安全的默认）。 */
export const DIR_LAYER: Readonly<Record<string, LayerName>> = {
  core: 'Kernel',
  math: 'Kernel',
  ecs: 'Kernel',
  generated: 'Kernel',
  render: 'Render',
  game: 'Game',
  apps: 'Game',
};

export interface Edge {
  readonly from: string;
  readonly to: string;
}

export interface UpwardViolation {
  readonly from: string;
  readonly fromLayer: LayerName;
  readonly to: string;
  readonly toLayer: LayerName;
}

/** 取路径的第一段目录名查层表；查不到时返回 fallback（默认 Kernel）。 */
export function layerOfPath(path: string, fallback: LayerName = 'Kernel'): LayerName {
  const top = path.split('/').filter(Boolean)[0] ?? '';
  return DIR_LAYER[top] ?? fallback;
}

/** 找所有「向上依赖」：起点层序小于终点层序的边。同层与向下都不算。 */
export function findUpwardDeps(
  edges: readonly Edge[],
  layerOf: (path: string) => LayerName = (p) => layerOfPath(p),
): UpwardViolation[] {
  const out: UpwardViolation[] = [];
  for (const e of edges) {
    const fl = layerOf(e.from);
    const tl = layerOf(e.to);
    if (LAYER_INDEX[fl] < LAYER_INDEX[tl]) {
      out.push({ from: e.from, fromLayer: fl, to: e.to, toLayer: tl });
    }
  }
  return out;
}

/** 用递归 DFS + 三色标记找有向环，每个环按发现顺序返回节点路径。 */
export function findCycles(nodes: readonly string[], edges: readonly Edge[]): string[][] {
  const adj = new Map<string, string[]>(nodes.map((n) => [n, []]));
  for (const e of edges) adj.get(e.from)?.push(e.to);

  const WHITE = 0, GRAY = 1, BLACK = 2;
  const color = new Map<string, number>(nodes.map((n) => [n, WHITE]));
  const path: string[] = [];
  const cycles: string[][] = [];

  const visit = (node: string): void => {
    color.set(node, GRAY);
    path.push(node);
    for (const nb of adj.get(node) ?? []) {
      const c = color.get(nb);
      if (c === WHITE) visit(nb);
      else if (c === GRAY) cycles.push(path.slice(path.indexOf(nb)));
    }
    path.pop();
    color.set(node, BLACK);
  };

  for (const n of nodes) if (color.get(n) === WHITE) visit(n);
  return cycles;
}

// snippet: src/core/module-graph.test.ts 的两条关键断言
it('内核 import 渲染被点名', () => {
  const v = findUpwardDeps([{ from: 'core/clock.ts', to: 'render/renderer.ts' }]);
  expect(v[0].fromLayer).toBe('Kernel');
  expect(v[0].toLayer).toBe('Render');
});

it('二元环与三元环都能找到', () => {
  const cycles = findCycles(['a.ts', 'b.ts', 'c.ts'], [
    { from: 'a.ts', to: 'b.ts' }, { from: 'b.ts', to: 'a.ts' },
    { from: 'b.ts', to: 'c.ts' }, { from: 'c.ts', to: 'b.ts' },
  ]);
  expect(cycles.length).toBe(2);
});

// file: tools/module-boundary-check.mjs
// tier: L1
// verify: node tools/module-boundary-check.mjs
//
// helio 工程化：扫描 src/ 的 import 图，检查两件事：
//   1) 依赖方向：只准上层 import 下层（Platform < Kernel < Render < Game）；
//   2) 循环依赖：任何 import 环都要被点名。
// 退出码 0 = 干净，1 = 有违规。CI 直接拿它当门禁。

import { readdirSync, readFileSync, statSync } from 'node:fs';
import { dirname, join, relative, resolve } from 'node:path';
import { findCycles, findUpwardDeps, layerOfPath } from '../src/core/module-graph.ts';

const ROOT = resolve(process.argv[2] ?? 'src');

function walk(dir) {
  const out = [];
  for (const name of readdirSync(dir)) {
    const p = join(dir, name);
    if (statSync(p).isDirectory()) out.push(...walk(p));
    else if (name.endsWith('.ts')) out.push(p);
  }
  return out;
}

/** 抠出所有相对说明符：`from './x.ts'` 与 `import('./x.ts')`。 */
function importsOf(src) {
  const specs = [];
  const re = /(?:from|import)\s*\(?\s*'([^']+)'/g;
  let m;
  while ((m = re.exec(src)) !== null) specs.push(m[1]);
  return specs.filter((s) => s.startsWith('.'));
}

const files = walk(ROOT).sort();
const nodes = new Set(files);
const edges = [];
for (const file of files) {
  for (const spec of importsOf(readFileSync(file, 'utf8'))) {
    const target = resolve(dirname(file), spec);
    if (nodes.has(target)) edges.push({ from: file, to: target });
  }
}

const upward = findUpwardDeps(edges, (p) => layerOfPath(relative(ROOT, p)));
const cycles = findCycles(files, edges);

const byLayer = {};
for (const f of files) {
  const l = layerOfPath(relative(ROOT, f));
  byLayer[l] = (byLayer[l] ?? 0) + 1;
}

console.log(`modules: ${files.length}`);
console.log(`edges:   ${edges.length}`);
console.log(`layers:  ${JSON.stringify(byLayer)}`);
console.log(`upward:  ${upward.length}`);
for (const v of upward) {
  console.log(`  ${v.fromLayer} -> ${v.toLayer}: ${relative(ROOT, v.from)} -> ${relative(ROOT, v.to)}`);
}
console.log(`cycles:  ${cycles.length}`);
for (const c of cycles) console.log(`  ${c.map((f) => relative(ROOT, f)).join(' -> ')}`);
process.exit(upward.length === 0 && cycles.length === 0 ? 0 : 1);

modules: 296
edges:   258
layers:  {"Game":11,"Kernel":135,"Render":150}
upward:  0
cycles:  0

modules: 297
edges:   259
layers:  {"Game":11,"Kernel":136,"Render":150}
upward:  1
  Kernel -> Render: core/__tmp_violation.ts -> render/renderer.ts
cycles:  0

$ npx tsc --noEmit
TypeScript: No errors found

$ npx vitest run src/core/module-graph.test.ts
Test Files  1 passed (1)
     Tests  6 passed (6)

$ node tools/module-boundary-check.mjs ; echo $?
0