《独立开发者的商业指南·资本与退出》6.2 客户与合同尽调

// file: src/capital/customer-dd.ts
// tier: L1
// verify: node --test test/capital/customer-dd.test.ts

import { type Cents } from "../core/money.ts";
import { type Bps, applyRate, divide } from "../core/rate.ts";
import { type Result, fail, ok } from "../core/result.ts";

export type CustomerShare = {
  name: string;
  revenueCents: Cents;
};

export type Concentration = {
  totalCents: Cents;
  customerCount: number;
  top1Cents: Cents;
  top1Bps: Bps;
  top3Bps: Bps;
  top5Bps: Bps;
};

function validCents(value: Cents): boolean {
  return Number.isInteger(value) && value >= 0;
}

function validBps(value: Bps): boolean {
  return Number.isInteger(value) && value >= 0 && value <= 10000;
}

/**
 * Concentration is measured on revenue, not on logo count. Ties keep the
 * input order so a report can explain why two customers with the same revenue
 * appear in a particular order.
 */
export function concentration(
  customers: CustomerShare[],
): Result<Concentration> {
  if (customers.length === 0) {
    return fail("at least one customer is required");
  }

  const seen = new Set<string>();
  let totalCents = 0;
  const rows: { row: CustomerShare; index: number }[] = [];
  for (const customer of customers) {
    if (customer.name.trim() === "") {
      return fail("customer name cannot be empty");
    }
    if (seen.has(customer.name)) {
      return fail(`duplicate customer ${customer.name}`);
    }
    if (!validCents(customer.revenueCents)) {
      return fail(
        `${customer.name} revenue must be a non-negative integer amount`,
      );
    }
    seen.add(customer.name);
    totalCents += customer.revenueCents;
    rows.push({ row: customer, index: rows.length });
  }
  if (totalCents === 0) {
    return fail("total customer revenue must be positive");
  }

  const ordered = rows
    .sort(
      (a, b) =>
        b.row.revenueCents - a.row.revenueCents || a.index - b.index,
    )
    .map((entry) => entry.row);

  const topN = (n: number): Cents =>
    ordered
      .slice(0, n)
      .reduce((acc, customer) => acc + customer.revenueCents, 0);

  const top1Cents = topN(1);

  return ok({
    totalCents,
    customerCount: rows.length,
    top1Cents,
    top1Bps: divide(top1Cents, totalCents),
    top3Bps: divide(topN(3), totalCents),
    top5Bps: divide(topN(5), totalCents),
  });
}

export type PriceBasis = "revenue" | "gross-profit";

export type LostCustomerInput = {
  annualRevenueCents: Cents;
  revenueShareBps: Bps;
  grossMarginBps: Bps;
  multipleBps: Bps;
  anchorPriceCents: Cents;
  basis: PriceBasis;
};

export type LostCustomerImpact = {
  lostRevenueCents: Cents;
  lostGrossProfitCents: Cents;
  priceImpactCents: Cents;
  impactBpsOfPrice: Bps;
};

/**
 * A revenue multiple loses revenue; an SDE multiple loses gross profit. The
 * two bases are kept explicit because using the wrong one overstates the cut
 * for a service business with subcontractors.
 */
export function lostCustomerImpact(
  input: LostCustomerInput,
): Result<LostCustomerImpact> {
  if (!Number.isInteger(input.annualRevenueCents) || input.annualRevenueCents <= 0) {
    return fail("annual revenue must be a positive integer amount");
  }
  if (!validBps(input.revenueShareBps)) {
    return fail("revenue share must be between 0 and 100%");
  }
  if (!validBps(input.grossMarginBps)) {
    return fail("gross margin must be between 0 and 100%");
  }
  if (!Number.isInteger(input.multipleBps) || input.multipleBps < 0) {
    return fail("multiple must be a non-negative integer in basis points");
  }
  if (
    !Number.isInteger(input.anchorPriceCents) ||
    input.anchorPriceCents <= 0
  ) {
    return fail("anchor price must be a positive integer amount");
  }
  if (input.basis !== "revenue" && input.basis !== "gross-profit") {
    return fail("basis must be revenue or gross-profit");
  }

  const lostRevenueCents = applyRate(
    input.annualRevenueCents,
    input.revenueShareBps,
  );
  const lostGrossProfitCents = applyRate(
    lostRevenueCents,
    input.grossMarginBps,
  );
  const basisCents =
    input.basis === "revenue" ? lostRevenueCents : lostGrossProfitCents;
  const priceImpactCents = Math.round(
    (basisCents * input.multipleBps) / 10000,
  );

  return ok({
    lostRevenueCents,
    lostGrossProfitCents,
    priceImpactCents,
    impactBpsOfPrice: divide(priceImpactCents, input.anchorPriceCents),
  });
}

export type AssignmentTerm = "free" | "consent" | "change-of-control";

export type ContractTerm = {
  id: string;
  annualRevenueCents: Cents;
  assignment: AssignmentTerm;
};

export type AssignabilityExposure = {
  totalCents: Cents;
  blockedCents: Cents;
  blockedBps: Bps;
  blockedCount: number;
  totalCount: number;
};

/**
 * Consent and change-of-control both block a clean transfer. They differ in
 * timing: consent is asked at assignment, while a change-of-control clause can
 * be triggered by the deal itself even when the contract stays with the same
 * legal entity.
 */
export function assignabilityExposure(
  contracts: ContractTerm[],
): Result<AssignabilityExposure> {
  if (contracts.length === 0) {
    return fail("at least one contract is required");
  }

  const seen = new Set<string>();
  let totalCents = 0;
  let blockedCents = 0;
  let blockedCount = 0;

  for (const contract of contracts) {
    if (contract.id.trim() === "") {
      return fail("contract id cannot be empty");
    }
    if (seen.has(contract.id)) {
      return fail(`duplicate contract ${contract.id}`);
    }
    if (!validCents(contract.annualRevenueCents)) {
      return fail(`${contract.id} revenue must be a non-negative integer amount`);
    }
    if (
      contract.assignment !== "free" &&
      contract.assignment !== "consent" &&
      contract.assignment !== "change-of-control"
    ) {
      return fail(`unknown assignment term ${contract.assignment}`);
    }
    seen.add(contract.id);
    totalCents += contract.annualRevenueCents;
    if (contract.assignment !== "free") {
      blockedCents += contract.annualRevenueCents;
      blockedCount += 1;
    }
  }

  if (totalCents === 0) {
    return fail("total contract revenue must be positive");
  }

  return ok({
    totalCents,
    blockedCents,
    blockedBps: divide(blockedCents, totalCents),
    blockedCount,
    totalCount: contracts.length,
  });
}