《移动游戏产品的架构·客户端与移动运行时》2.3 边界测试：依赖规则写成可执行断言

// file: src/core/boundaries.ts
// tier: L1
// verify: node --test test/core/boundaries.test.ts

import {
  classifyDependency,
  findUpwardEdges,
  type DependencyKind,
  type Layer,
  type LayerEdge,
} from "./layers.ts";

export interface ModuleRef {
  readonly module: string;
  readonly layer: Layer;
}

export interface ModuleNode extends ModuleRef {
  readonly imports: readonly ModuleRef[];
}

export interface ImportEdge {
  readonly from: ModuleRef;
  readonly to: ModuleRef;
  readonly direction: DependencyKind;
  readonly allowed: boolean;
}

export function classifyImport(from: ModuleRef, to: ModuleRef): ImportEdge {
  const direction = classifyDependency(from.layer, to.layer);
  return {
    from,
    to,
    direction,
    allowed: direction !== "upward",
  };
}

function edgesOf(nodes: readonly ModuleNode[]): readonly ImportEdge[] {
  const edges: ImportEdge[] = [];
  for (const node of nodes) {
    const from: ModuleRef = { module: node.module, layer: node.layer };
    for (const target of node.imports) {
      edges.push(classifyImport(from, target));
    }
  }
  return edges;
}

export function findCrossLayerImports(nodes: readonly ModuleNode[]): readonly ImportEdge[] {
  return edgesOf(nodes).filter((edge) => edge.from.layer !== edge.to.layer);
}

export function findUpwardImports(nodes: readonly ModuleNode[]): readonly ImportEdge[] {
  return edgesOf(nodes).filter((edge) => edge.direction === "upward");
}

export interface UnknownImport {
  readonly from: ModuleRef;
  readonly to: ModuleRef;
}

export function findUnknownImports(nodes: readonly ModuleNode[]): readonly UnknownImport[] {
  const known = new Set(nodes.map((node) => node.module));
  return edgesOf(nodes)
    .filter((edge) => !known.has(edge.to.module))
    .map((edge) => ({ from: edge.from, to: edge.to }));
}

export function assertLayerEdges(product: string, edges: readonly LayerEdge[]): void {
  const upward = findUpwardEdges(edges);
  if (upward.length > 0) {
    const paths = upward.map((edge) => `${edge.from}->${edge.to}`).join(", ");
    throw new Error(`${product}: upward layer edges: ${paths}`);
  }
}

export interface ModuleGraphReport {
  readonly product: string;
  readonly modules: number;
  readonly crossLayerImports: readonly ImportEdge[];
  readonly upwardImports: readonly ImportEdge[];
  readonly unknownImports: readonly UnknownImport[];
  readonly sameLayerImports: number;
  readonly passed: boolean;
}

export function moduleGraphReport(
  product: string,
  nodes: readonly ModuleNode[],
): ModuleGraphReport {
  const ids = new Set(nodes.map((node) => node.module));
  if (ids.size !== nodes.length) {
    throw new Error(`${product}: duplicate module ids in graph`);
  }
  const all = edgesOf(nodes);
  const upwardImports = all.filter((edge) => edge.direction === "upward");
  const unknownImports = findUnknownImports(nodes);
  return {
    product,
    modules: nodes.length,
    crossLayerImports: all.filter((edge) => edge.from.layer !== edge.to.layer),
    upwardImports,
    unknownImports,
    sameLayerImports: all.filter((edge) => edge.direction === "same-layer").length,
    passed: upwardImports.length === 0 && unknownImports.length === 0,
  };
}

export function assertModuleGraph(report: ModuleGraphReport): void {
  if (report.passed) {
    return;
  }
  const upward = report.upwardImports
    .map((edge) => `${edge.from.module}(${edge.from.layer})->${edge.to.module}(${edge.to.layer})`)
    .join(", ");
  const unknown = report.unknownImports
    .map((edge) => `${edge.from.module}->${edge.to.module}`)
    .join(", ");
  throw new Error(
    `${report.product}: boundary violations; upward=[${upward}] unknown=[${unknown}]`,
  );
}

export interface DualGraphReport {
  readonly products: readonly ModuleGraphReport[];
  readonly modules: number;
  readonly upwardImports: number;
  readonly unknownImports: number;
  readonly passed: boolean;
}

export function dualGraphReport(
  first: ModuleGraphReport,
  second: ModuleGraphReport,
): DualGraphReport {
  return {
    products: [first, second],
    modules: first.modules + second.modules,
    upwardImports: first.upwardImports.length + second.upwardImports.length,
    unknownImports: first.unknownImports.length + second.unknownImports.length,
    passed: first.passed && second.passed,
  };
}

export const DECLARED_LAYER_EDGES: readonly LayerEdge[] = [
  { from: "presentation", to: "gameplay" },
  { from: "presentation", to: "system" },
  { from: "gameplay", to: "system" },
  { from: "system", to: "platform" },
];

export const MATCH3_MODULES: readonly ModuleNode[] = [
  {
    module: "board-view",
    layer: "presentation",
    imports: [
      { module: "match3-core", layer: "gameplay" },
      { module: "activity-banner", layer: "presentation" },
      { module: "ui-kit", layer: "presentation" },
    ],
  },
  {
    module: "activity-banner",
    layer: "presentation",
    imports: [{ module: "activity-config", layer: "system" }],
  },
  { module: "ui-kit", layer: "presentation", imports: [] },
  {
    module: "match3-core",
    layer: "gameplay",
    imports: [
      { module: "levels", layer: "gameplay" },
      { module: "save-service", layer: "system" },
    ],
  },
  { module: "levels", layer: "gameplay", imports: [] },
  {
    module: "save-service",
    layer: "system",
    imports: [{ module: "host-fs", layer: "platform" }],
  },
  {
    module: "activity-config",
    layer: "system",
    imports: [{ module: "host-fs", layer: "platform" }],
  },
  { module: "host-fs", layer: "platform", imports: [] },
];

export const ARK_MODULES: readonly ModuleNode[] = [
  {
    module: "battle-hud",
    layer: "presentation",
    imports: [
      { module: "battle-core", layer: "gameplay" },
      { module: "battle-net", layer: "system" },
      { module: "battle-log", layer: "presentation" },
    ],
  },
  { module: "battle-log", layer: "presentation", imports: [] },
  {
    module: "battle-core",
    layer: "gameplay",
    imports: [
      { module: "battle-rules", layer: "gameplay" },
      { module: "card-config", layer: "system" },
    ],
  },
  { module: "battle-rules", layer: "gameplay", imports: [] },
  {
    module: "battle-net",
    layer: "system",
    imports: [
      { module: "socket-host", layer: "platform" },
      { module: "account-client", layer: "system" },
    ],
  },
  {
    module: "account-client",
    layer: "system",
    imports: [{ module: "session-host", layer: "platform" }],
  },
  {
    module: "card-config",
    layer: "system",
    imports: [{ module: "asset-host", layer: "platform" }],
  },
  { module: "socket-host", layer: "platform", imports: [] },
  { module: "session-host", layer: "platform", imports: [] },
  { module: "asset-host", layer: "platform", imports: [] },
];