《互联网产品的客户端架构·端形态与体验基础》13.2 模块划分与依赖图

// file: src/summary/module-dependency.ts
// tier: L1
// verify: node --test test/summary/module-dependency.test.ts

export type GraphLayer = "summary" | "view" | "state" | "domain" | "data" | "shared";

export interface ModuleRecord {
  id: string;
  layer: GraphLayer;
  /** 本模块静态依赖的模块 id */
  imports: string[];
}

export interface GraphEdge {
  from: string;
  to: string;
}

export interface DirectionViolation {
  from: string;
  to: string;
  message: string;
}

export interface DependencyReport {
  modules: string[];
  edges: GraphEdge[];
  cycles: string[][];
  directionViolations: DirectionViolation[];
  missing: string[];
  fanIn: Record<string, number>;
  fanOut: Record<string, number>;
  order: string[];
  blocked: string[];
  status: "pass" | "fail";
}

/** 数字越大越靠外；依赖只允许从大到小，summary 是卷一的组合根。 */
export const LAYER_RANK: Record<GraphLayer, number> = {
  summary: 4,
  view: 3,
  state: 2,
  domain: 1,
  data: 0,
  shared: -1,
};

interface Normalized {
  names: string[];
  layers: Map<string, GraphLayer>;
  adj: Map<string, string[]>;
}

function normalize(modules: ModuleRecord[]): Normalized {
  const names: string[] = [];
  const layers = new Map<string, GraphLayer>();
  for (const module of modules) {
    if (layers.has(module.id)) throw new Error(`重复模块: ${module.id}`);
    layers.set(module.id, module.layer);
    names.push(module.id);
  }
  names.sort();

  const adj = new Map<string, string[]>();
  for (const name of names) adj.set(name, []);
  for (const module of modules) {
    const targets = [...new Set(module.imports)].sort();
    adj.set(module.id, targets);
  }
  return { names, layers, adj };
}

/** 在 blocked 集合内找一条回到 start 的具体回路，找不到返回 undefined。 */
function cycleFrom(
  start: string,
  adj: Map<string, string[]>,
  allowed: Set<string>,
): string[] | undefined {
  const path: string[] = [];
  const onPath = new Set<string>();

  const walk = (node: string): string[] | undefined => {
    path.push(node);
    onPath.add(node);
    for (const next of adj.get(node) ?? []) {
      if (next === start) return [...path, start];
      if (!allowed.has(next) || onPath.has(next)) continue;
      const found = walk(next);
      if (found) return found;
    }
    path.pop();
    onPath.delete(node);
    return undefined;
  };

  return walk(start);
}

/**
 * 从一张模块清单构建依赖图，并一次产出循环、方向、悬空引用与构建顺序。
 * 不读文件系统：清单由构建脚本扫描后传入，纯函数可在测试里完整覆盖。
 */
export function buildDependencyReport(modules: ModuleRecord[]): DependencyReport {
  const { names, layers, adj } = normalize(modules);
  const known = new Set(names);
  const edges: GraphEdge[] = [];
  const missing = new Set<string>();

  for (const from of names) {
    for (const to of adj.get(from) ?? []) {
      edges.push({ from, to });
      if (!known.has(to)) missing.add(to);
    }
  }

  const directionViolations: DirectionViolation[] = [];
  for (const edge of edges) {
    const fromLayer = layers.get(edge.from) as GraphLayer;
    const toLayer = layers.get(edge.to);
    if (!toLayer) continue;
    if (LAYER_RANK[toLayer] > LAYER_RANK[fromLayer]) {
      directionViolations.push({
        from: edge.from,
        to: edge.to,
        message: `${edge.from}(${fromLayer}) 依赖了更外层的 ${edge.to}(${toLayer})`,
      });
    }
  }
  directionViolations.sort(
    (a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to),
  );

  const indegree = new Map<string, number>();
  const dependents = new Map<string, string[]>();
  for (const name of names) {
    indegree.set(name, 0);
    dependents.set(name, []);
  }
  for (const edge of edges) {
    if (!known.has(edge.to)) continue;
    indegree.set(edge.from, (indegree.get(edge.from) ?? 0) + 1);
    dependents.get(edge.to)?.push(edge.from);
  }

  const ready = names.filter((name) => indegree.get(name) === 0).sort();
  const order: string[] = [];
  while (ready.length > 0) {
    const node = ready.shift() as string;
    order.push(node);
    for (const dependent of dependents.get(node) ?? []) {
      const left = (indegree.get(dependent) ?? 0) - 1;
      indegree.set(dependent, left);
      if (left === 0) ready.push(dependent);
    }
    ready.sort();
  }

  const emitted = new Set(order);
  const blocked = names.filter((name) => !emitted.has(name));
  const blockedSet = new Set(blocked);
  const cycles: string[][] = [];
  const covered = new Set<string>();
  for (const start of blocked) {
    if (covered.has(start)) continue;
    const path = cycleFrom(start, adj, blockedSet);
    if (!path) continue;
    cycles.push(path);
    for (const node of path) covered.add(node);
  }
  cycles.sort((a, b) => a.join(">").localeCompare(b.join(">")));

  const fanIn: Record<string, number> = {};
  const fanOut: Record<string, number> = {};
  for (const name of names) {
    fanIn[name] = 0;
    fanOut[name] = (adj.get(name) ?? []).length;
  }
  for (const edge of edges) {
    if (known.has(edge.to)) fanIn[edge.to] = (fanIn[edge.to] ?? 0) + 1;
  }

  const status =
    cycles.length === 0 &&
    directionViolations.length === 0 &&
    missing.size === 0
      ? "pass"
      : "fail";

  return {
    modules: names,
    edges,
    cycles,
    directionViolations,
    missing: [...missing].sort(),
    fanIn,
    fanOut,
    order,
    blocked,
    status,
  };
}

/** 输出稳定文本，便于贴进 CI 日志或基线评审记录。 */
export function formatDependencyReport(report: DependencyReport): string[] {
  const lines = [
    `已检查 ${report.modules.length} 个模块，${report.edges.length} 条依赖`,
    `构建顺序：${report.order.join(" -> ") || "无"}`,
  ];
  const topFanIn = Object.entries(report.fanIn)
    .filter(([, count]) => count > 0)
    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
    .slice(0, 3);
  lines.push(
    `被依赖最多：${
      topFanIn.map(([id, count]) => `${id}(${count})`).join(", ") || "无"
    }`,
  );
  for (const cycle of report.cycles) lines.push(`循环依赖：${cycle.join(" -> ")}`);
  for (const violation of report.directionViolations) {
    lines.push(`方向违规：${violation.message}`);
  }
  for (const id of report.missing) lines.push(`悬空引用：${id}`);
  if (report.status === "pass") lines.push("结果：pass");
  else lines.push(`结果：fail（阻塞 ${report.blocked.length} 个模块）`);
  return lines;
}

node --test test/summary/module-dependency.test.ts

✔ 卷一真实依赖图无循环、无反向、无悬空引用 (0.996458ms)
✔ 同层三角依赖被 Kahn 拓扑识别为循环并给出一条回路 (0.1925ms)
✔ 数据层反向依赖视图层会被判为方向违规 (0.153542ms)
✔ 引用清单里不存在的模块会进入 missing 并让结果失败 (0.097333ms)
✔ 文本输出包含顺序、热点与结论，可直接贴进评审记录 (9.100459ms)
ℹ tests 5
ℹ suites 0
ℹ pass 5
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 158.524333