《互联网产品的客户端架构·规模化与架构演进》11.2 代码所有权与评审

// file: src/governance/code-ownership.ts
// tier: L1
// verify: node --test test/governance/code-ownership.test.ts

export type OwnerRule = {
  pattern: string;
  owner: string;
  reviewers?: string[];
  priority?: number;
};

export type OwnerMatch = {
  path: string;
  owner: string;
  pattern: string;
  priority: number;
  reviewers: string[];
};

export type CoverageReport = {
  total: number;
  owned: number;
  unowned: string[];
  ratio: number;
};

export type ReviewRoute = {
  owners: string[];
  reviewers: string[];
  unowned: string[];
  escalate: boolean;
};

function escapeRegExp(text: string): string {
  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}

export function normalizePath(input: string): string {
  let path = input.trim().replace(/\\/g, "/");
  while (path.startsWith("./")) {
    path = path.slice(2);
  }
  return path.replace(/\/+$/, "");
}

export function matchPattern(pattern: string, target: string): boolean {
  const p = normalizePath(pattern);
  const path = normalizePath(target);
  if (p.endsWith("/**")) {
    const base = p.slice(0, -3);
    return path === base || path.startsWith(`${base}/`);
  }
  if (!p.includes("*")) {
    return p === path;
  }
  const source = p
    .split("**")
    .map((part) => part.split("*").map(escapeRegExp).join("[^/]*"))
    .join(".*");
  return new RegExp(`^${source}$`).test(path);
}

export function resolveOwner(rules: OwnerRule[], target: string): OwnerMatch | undefined {
  let best: OwnerMatch | undefined;
  for (const rule of rules) {
    if (!matchPattern(rule.pattern, target)) {
      continue;
    }
    const priority = rule.priority ?? 0;
    if (best === undefined || priority > best.priority) {
      best = {
        path: normalizePath(target),
        owner: rule.owner,
        pattern: rule.pattern,
        priority,
        reviewers: [...(rule.reviewers ?? [])],
      };
    }
  }
  return best;
}

export function resolveAll(rules: OwnerRule[], paths: string[]): OwnerMatch[] {
  const matches: OwnerMatch[] = [];
  for (const path of paths) {
    const match = resolveOwner(rules, path);
    if (match !== undefined) {
      matches.push(match);
    }
  }
  return matches;
}

export function coverageReport(rules: OwnerRule[], paths: string[]): CoverageReport {
  const unowned = paths
    .filter((path) => resolveOwner(rules, path) === undefined)
    .map((path) => normalizePath(path));
  const total = paths.length;
  const owned = total - unowned.length;
  return {
    total,
    owned,
    unowned,
    ratio: total === 0 ? 1 : owned / total,
  };
}

export function unownedPaths(rules: OwnerRule[], paths: string[]): string[] {
  return coverageReport(rules, paths).unowned;
}

export function coverageByOwner(rules: OwnerRule[], paths: string[]): Record<string, number> {
  const counts: Record<string, number> = {};
  for (const path of paths) {
    const match = resolveOwner(rules, path);
    if (match === undefined) {
      continue;
    }
    counts[match.owner] = (counts[match.owner] ?? 0) + 1;
  }
  return counts;
}

export function busiestOwner(rules: OwnerRule[], paths: string[]): string | undefined {
  const counts = coverageByOwner(rules, paths);
  let best: string | undefined;
  for (const [owner, count] of Object.entries(counts)) {
    if (best === undefined || count > counts[best]) {
      best = owner;
    }
  }
  return best;
}

export function reviewRoute(
  rules: OwnerRule[],
  paths: string[],
  fallback?: string,
): ReviewRoute {
  const owners = new Set<string>();
  const reviewers = new Set<string>();
  const unowned: string[] = [];
  for (const path of paths) {
    const match = resolveOwner(rules, path);
    if (match === undefined) {
      unowned.push(normalizePath(path));
      if (fallback !== undefined) {
        owners.add(fallback);
      }
      continue;
    }
    owners.add(match.owner);
    for (const reviewer of match.reviewers) {
      reviewers.add(reviewer);
    }
  }
  return {
    owners: [...owners].sort(),
    reviewers: [...reviewers].sort(),
    unowned: [...new Set(unowned)].sort(),
    escalate: unowned.length > 0,
  };
}

export function staleRules(rules: OwnerRule[], paths: string[]): string[] {
  return rules
    .filter((rule) => !paths.some((path) => matchPattern(rule.pattern, path)))
    .map((rule) => rule.pattern);
}

export function fullyOwned(rules: OwnerRule[], paths: string[]): boolean {
  return unownedPaths(rules, paths).length === 0;
}