the App's rate limit never grew with the installation

"""Say whether a GitHub App installation has the rate-limit ceiling it earns.

Read only. Two GETs: the rate-limit endpoint, which does not consume quota, and
a one-item page of the installation's repositories, which is the cheapest way to
learn how big the installation is. Nothing is minted, widened or changed.

An installation's hourly ceiling starts at 5,000 and grows with the number of
repositories and users the installation covers, to a maximum of 12,500; an
Enterprise Cloud organization gets a flat 15,000 instead. An installation
restricted to a handful of selected repositories never earns the growth, so a
large organization behind a narrow installation throttles at the same ceiling a
single user gets.

This is not the note about draining an hourly window. It is about the size of
the window before anything draws from it.

Environment:

    GITHUB_INSTALLATION_TOKEN   an installation access token
"""
import argparse
import json
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("github_app_limit_ceiling")

API = "https://api.github.com"
UA = "github-app-limit-ceiling/1.0"

# The documented shape of the ceiling. Kept as named constants because every one
# of them turns up in the output, and a reader comparing the script against the
# documentation should be able to find them in one place.
BASELINE = 5000
PER_UNIT = 50
SCALING_FLOOR = 20
FREE_CEILING = 12500
ENTERPRISE_CEILING = 15000
ANONYMOUS = 60


def entitled(repositories, users=None, enterprise=False):
    """The hourly ceiling an installation of this size earns. Pure.

    users is allowed to be None, because a read-only installation token usually
    cannot count the members of an organization. The user term only ever adds,
    so treating an unknown count as zero makes the result a lower bound rather
    than a guess: a measured limit below this number is a real shortfall
    whatever the true membership is.
    """
    if enterprise:
        return ENTERPRISE_CEILING
    try:
        repos = int(repositories or 0)
    except (TypeError, ValueError):
        repos = 0
    try:
        people = int(users or 0)
    except (TypeError, ValueError):
        people = 0
    extra = max(0, repos - SCALING_FLOOR) + max(0, people - SCALING_FLOOR)
    return min(FREE_CEILING, BASELINE + PER_UNIT * extra)


def is_lower_bound(users):
    """Whether the entitlement was computed without the user term. Pure."""
    return users is None


def classify_ceiling(limit):
    """Name the ceiling a credential was actually given. Pure.

    The names matter more than the numbers downstream, because the repair for a
    ceiling that sits at the floor and the repair for one already at the cap are
    opposite pieces of advice.
    """
    try:
        value = int(limit)
    except (TypeError, ValueError):
        return "unknown"
    if value == ANONYMOUS:
        return "unauthenticated"
    if value == ENTERPRISE_CEILING:
        return "enterprise"
    if value == FREE_CEILING:
        return "at-cap"
    if value == BASELINE:
        return "baseline"
    if BASELINE < value < FREE_CEILING:
        return "scaled"
    return "unknown"


def selection_of(view):
    """The repository_selection on an installation view, normalised. Pure."""
    if not isinstance(view, dict):
        return "unknown"
    raw = str(view.get("repository_selection") or "").strip().lower()
    return raw if raw in ("all", "selected") else "unknown"


def reachable(view):
    """How many repositories the installation covers, or None. Pure."""
    if not isinstance(view, dict):
        return None
    raw = view.get("total_count")
    if raw is None:
        return None
    try:
        return int(raw)
    except (TypeError, ValueError):
        return None


def shortfall(limit, entitlement):
    """Requests an hour the installation is not getting, or 0. Pure."""
    try:
        have, earned = int(limit), int(entitlement)
    except (TypeError, ValueError):
        return 0
    return max(0, earned - have)


def sustainable_repos(limit, calls_per_repo):
    """How many repositories a loop of this cost fits under the ceiling. Pure."""
    try:
        ceiling, cost = int(limit), int(calls_per_repo)
    except (TypeError, ValueError):
        return None
    if cost <= 0:
        return None
    return ceiling // cost


def verdict(limit, selection, covered, account_repos=None, users=None,
            enterprise=False, installation_seen=True):
    """Turn the two reads into a finding. Pure.

    covered is the size of the installation. account_repos, where the caller
    could learn it, is the size of the account behind the installation: the
    difference between those two is what makes a narrow installation narrow.
    """
    klass = classify_ceiling(limit)
    if klass == "unauthenticated":
        return ("unauthenticated",
                "the ceiling is 60/hour, which is the anonymous ceiling. This "
                "credential is not reaching GitHub as an installation at all.")
    if not installation_seen:
        return ("not-an-installation",
                "the ceiling is %s/hour and the installation endpoint did not "
                "answer, so this is a user or Actions credential rather than an "
                "installation token. Installation scaling does not apply to it."
                % limit)
    if klass == "enterprise":
        return ("enterprise",
                "the ceiling is 15000/hour, the flat Enterprise Cloud ceiling. "
                "Widening the installation cannot raise it further.")
    earned = entitled(account_repos if account_repos is not None else covered,
                      users, enterprise)
    if klass == "at-cap":
        return ("at-cap",
                "the ceiling is 12500/hour, the maximum outside Enterprise "
                "Cloud. There is no more to earn: spend fewer requests.")
    gap = shortfall(limit, earned)
    if gap and selection == "selected":
        return ("narrow-installation",
                "the ceiling is %s/hour, and an installation covering %s "
                "repositories would be entitled to at least %d/hour. The "
                "selection is what is capping it, not the account."
                % (limit, account_repos if account_repos is not None else covered,
                   earned))
    if gap:
        return ("below-entitlement",
                "the ceiling is %s/hour against an entitlement of at least "
                "%d/hour for this size. The installation is narrower than the "
                "size used for the comparison." % (limit, earned))
    if klass == "baseline":
        return ("baseline",
                "the ceiling is 5000/hour and the installation covers %s "
                "repositories, which is too few to earn any scaling. This "
                "ceiling is real: the repair is on the usage side."
                % covered)
    return ("scaled",
            "the ceiling is %s/hour, which matches an installation this size."
            % limit)


def repair(state, covered=None, account_repos=None):
    """The sentence a reader has to act on. Pure."""
    if state == "narrow-installation":
        return ("widen the installation to all repositories if the App "
                "legitimately needs org-wide reach, which raises the ceiling as "
                "a side effect. If it does not, keep the narrow selection and "
                "cut request volume instead: conditional requests, a bigger "
                "per_page, one GraphQL query for a fan-out of REST calls.")
    if state in ("at-cap", "enterprise", "baseline"):
        return ("nothing on the installation. This ceiling is the one you get, "
                "so the only lever left is spending fewer requests per unit of "
                "work.")
    if state == "unauthenticated":
        return ("send the installation access token in the Authorization "
                "header. Nothing about scaling matters while the requests are "
                "arriving anonymously.")
    if state == "not-an-installation":
        return ("point the check at an installation access token. A user token "
                "gets a flat 5000 and never scales, so comparing it against an "
                "installation entitlement is meaningless.")
    if state == "below-entitlement":
        return ("check repository_selection and the account behind the "
                "installation before widening anything: the numbers disagree "
                "for a reason this script could not see.")
    return "nothing."


def get(session, path):
    """One GET. Returns (status, json-or-None)."""
    url = API + path if path.startswith("/") else path
    r = session.get(url, timeout=30)
    try:
        body = r.json()
    except ValueError:
        body = None
    return r.status_code, body


def core_limits(session):
    """The core and graphql ceilings from the free rate-limit endpoint."""
    status, body = get(session, "/rate_limit")
    if status != 200 or not isinstance(body, dict):
        log.error("GET /rate_limit returned %d", status)
        return None, None
    resources = body.get("resources") or {}
    core = (resources.get("core") or {}).get("limit")
    graphql = (resources.get("graphql") or {}).get("limit")
    return core, graphql


def installation_view(session):
    """total_count and repository_selection, without fetching repositories."""
    status, body = get(session, "/installation/repositories?per_page=1")
    if status != 200 or not isinstance(body, dict):
        return None
    return body


def account_size(session, org):
    """Repositories on the account behind the installation, where readable."""
    if not org:
        return None
    status, body = get(session, "/orgs/%s" % org)
    if status != 200 or not isinstance(body, dict):
        log.info("GET /orgs/%s returned %d; the account size is not readable "
                 "from here, so the comparison uses the installation size",
                 org, status)
        return None
    public = body.get("public_repos") or 0
    private = body.get("total_private_repos") or 0
    try:
        return int(public) + int(private)
    except (TypeError, ValueError):
        return None


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--org", default=os.environ.get("GITHUB_ORG"),
                    help="the account behind the installation, to size it")
    ap.add_argument("--users", type=int, default=None,
                    help="members of that account, if you know it; the API "
                         "rarely tells a read-only installation token")
    ap.add_argument("--calls-per-repo", type=int, default=10,
                    help="calls your loop makes per repository per hour")
    ap.add_argument("--enterprise", action="store_true",
                    help="the account is on GitHub Enterprise Cloud")
    args = ap.parse_args()

    token = os.environ.get("GITHUB_INSTALLATION_TOKEN")
    if not token:
        log.error("set GITHUB_INSTALLATION_TOKEN to an installation access "
                  "token. A user token has a flat ceiling and nothing here "
                  "applies to it")
        return 2

    session = requests.Session()
    session.headers.update({
        "Authorization": "Bearer " + token,
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28",
        "User-Agent": UA,
    })

    core, graphql = core_limits(session)
    if core is None:
        return 2
    log.info("core ceiling: %s/hour, graphql %s/hour", core, graphql)

    view = installation_view(session)
    covered = reachable(view)
    selection = selection_of(view)
    if view is None:
        log.info("the installation endpoint did not answer for this token")
    else:
        log.info("installation: repository_selection=%s, %s repository/"
                 "repositories reachable", selection, covered)

    org_repos = account_size(session, args.org) if selection == "selected" else None
    state, detail = verdict(core, selection, covered, org_repos, args.users,
                            args.enterprise, installation_seen=view is not None)
    log.info("%s: %s", state, detail)
    log.info("repair: %s", repair(state, covered, org_repos))

    fits = sustainable_repos(core, args.calls_per_repo)
    if fits is not None:
        log.info("budget: %s/hour serves %d repositories at %d call(s) each",
                 core, fits, args.calls_per_repo)

    print(json.dumps({
        "core_limit": core,
        "graphql_limit": graphql,
        "repository_selection": selection,
        "repositories_covered": covered,
        "account_repositories": org_repos,
        "entitlement_is_lower_bound": is_lower_bound(args.users),
        "entitled": entitled(org_repos if org_repos is not None else covered,
                             args.users, args.enterprise),
        "ceiling_class": classify_ceiling(core),
        "state": state,
        "detail": detail,
        "repositories_supported": fits,
    }, indent=2, default=str))
    return 1 if state in ("narrow-installation", "below-entitlement",
                          "unauthenticated") else 0


if __name__ == "__main__":
    sys.exit(main())

/**
 * Say whether a GitHub App installation has the rate-limit ceiling it earns.
 *
 * Read only. Two GETs: the rate-limit endpoint, which does not consume quota,
 * and a one-item page of the installation's repositories. Nothing is minted,
 * widened or changed.
 *
 * Environment:
 *   GITHUB_INSTALLATION_TOKEN  an installation access token
 *   GITHUB_ORG                 optional, the account behind the installation
 */
const API = 'https://api.github.com';
const UA = 'github-app-limit-ceiling/1.0';

/** The documented shape of the ceiling. */
export const BASELINE = 5000;
export const PER_UNIT = 50;
export const SCALING_FLOOR = 20;
export const FREE_CEILING = 12500;
export const ENTERPRISE_CEILING = 15000;
export const ANONYMOUS = 60;

/**
 * The hourly ceiling an installation of this size earns. Pure.
 * users may be null: the user term only adds, so an unknown count makes the
 * answer a lower bound rather than a guess.
 */
export function entitled(repositories, users = null, enterprise = false) {
  if (enterprise) return ENTERPRISE_CEILING;
  const repos = Number.isFinite(Number(repositories)) ? Number(repositories) : 0;
  const people = Number.isFinite(Number(users)) ? Number(users) : 0;
  const extra = Math.max(0, repos - SCALING_FLOOR) + Math.max(0, people - SCALING_FLOOR);
  return Math.min(FREE_CEILING, BASELINE + PER_UNIT * extra);
}

/** Whether the entitlement was computed without the user term. Pure. */
export function isLowerBound(users) {
  return users === null || users === undefined;
}

/** Name the ceiling a credential was actually given. Pure. */
export function classifyCeiling(limit) {
  const value = Number(limit);
  if (!Number.isFinite(value)) return 'unknown';
  if (value === ANONYMOUS) return 'unauthenticated';
  if (value === ENTERPRISE_CEILING) return 'enterprise';
  if (value === FREE_CEILING) return 'at-cap';
  if (value === BASELINE) return 'baseline';
  if (value > BASELINE && value < FREE_CEILING) return 'scaled';
  return 'unknown';
}

/** The repository_selection on an installation view, normalised. Pure. */
export function selectionOf(view) {
  if (!view || typeof view !== 'object') return 'unknown';
  const raw = String(view.repository_selection ?? '').trim().toLowerCase();
  return ['all', 'selected'].includes(raw) ? raw : 'unknown';
}

/** How many repositories the installation covers, or null. Pure. */
export function reachable(view) {
  if (!view || typeof view !== 'object') return null;
  const raw = view.total_count;
  if (raw === null || raw === undefined) return null;
  const n = Number(raw);
  return Number.isFinite(n) ? Math.trunc(n) : null;
}

/** Requests an hour the installation is not getting, or 0. Pure. */
export function shortfall(limit, entitlement) {
  const num = (v) => (v === null || v === undefined || v === '' ? NaN : Number(v));
  const have = num(limit);
  const earned = num(entitlement);
  if (!Number.isFinite(have) || !Number.isFinite(earned)) return 0;
  return Math.max(0, earned - have);
}

/** How many repositories a loop of this cost fits under the ceiling. Pure. */
export function sustainableRepos(limit, callsPerRepo) {
  const ceiling = Number(limit);
  const cost = Number(callsPerRepo);
  if (!Number.isFinite(ceiling) || !Number.isFinite(cost) || cost <= 0) return null;
  return Math.floor(ceiling / cost);
}

/** Turn the two reads into a finding. Pure. */
export function verdict(limit, selection, covered, accountRepos = null,
                        users = null, enterprise = false, installationSeen = true) {
  const klass = classifyCeiling(limit);
  if (klass === 'unauthenticated') {
    return ['unauthenticated',
      'the ceiling is 60/hour, which is the anonymous ceiling. This credential '
      + 'is not reaching GitHub as an installation at all.'];
  }
  if (!installationSeen) {
    return ['not-an-installation',
      `the ceiling is ${limit}/hour and the installation endpoint did not `
      + 'answer, so this is a user or Actions credential rather than an '
      + 'installation token. Installation scaling does not apply to it.'];
  }
  if (klass === 'enterprise') {
    return ['enterprise',
      'the ceiling is 15000/hour, the flat Enterprise Cloud ceiling. Widening '
      + 'the installation cannot raise it further.'];
  }
  const size = accountRepos === null || accountRepos === undefined ? covered : accountRepos;
  const earned = entitled(size, users, enterprise);
  if (klass === 'at-cap') {
    return ['at-cap',
      'the ceiling is 12500/hour, the maximum outside Enterprise Cloud. There '
      + 'is no more to earn: spend fewer requests.'];
  }
  const gap = shortfall(limit, earned);
  if (gap && selection === 'selected') {
    return ['narrow-installation',
      `the ceiling is ${limit}/hour, and an installation covering ${size} `
      + `repositories would be entitled to at least ${earned}/hour. The `
      + 'selection is what is capping it, not the account.'];
  }
  if (gap) {
    return ['below-entitlement',
      `the ceiling is ${limit}/hour against an entitlement of at least `
      + `${earned}/hour for this size. The installation is narrower than the `
      + 'size used for the comparison.'];
  }
  if (klass === 'baseline') {
    return ['baseline',
      `the ceiling is 5000/hour and the installation covers ${covered} `
      + 'repositories, which is too few to earn any scaling. This ceiling is '
      + 'real: the repair is on the usage side.'];
  }
  return ['scaled', `the ceiling is ${limit}/hour, which matches an installation this size.`];
}

/** The sentence a reader has to act on. Pure. */
export function repair(state) {
  if (state === 'narrow-installation') {
    return 'widen the installation to all repositories if the App legitimately '
      + 'needs org-wide reach, which raises the ceiling as a side effect. If it '
      + 'does not, keep the narrow selection and cut request volume instead: '
      + 'conditional requests, a bigger per_page, one GraphQL query for a '
      + 'fan-out of REST calls.';
  }
  if (['at-cap', 'enterprise', 'baseline'].includes(state)) {
    return 'nothing on the installation. This ceiling is the one you get, so '
      + 'the only lever left is spending fewer requests per unit of work.';
  }
  if (state === 'unauthenticated') {
    return 'send the installation access token in the Authorization header. '
      + 'Nothing about scaling matters while the requests are arriving anonymously.';
  }
  if (state === 'not-an-installation') {
    return 'point the check at an installation access token. A user token gets '
      + 'a flat 5000 and never scales, so comparing it against an installation '
      + 'entitlement is meaningless.';
  }
  if (state === 'below-entitlement') {
    return 'check repository_selection and the account behind the installation '
      + 'before widening anything: the numbers disagree for a reason this '
      + 'script could not see.';
  }
  return 'nothing.';
}

function headers(token) {
  return {
    Authorization: `Bearer ${token}`,
    Accept: 'application/vnd.github+json',
    'X-GitHub-Api-Version': '2022-11-28',
    'User-Agent': UA,
  };
}

async function get(token, path) {
  const res = await fetch(API + path, { headers: headers(token) });
  let body = null;
  try { body = await res.json(); } catch { body = null; }
  return { status: res.status, body };
}

async function main() {
  const token = process.env.GITHUB_INSTALLATION_TOKEN;
  if (!token) {
    console.error('set GITHUB_INSTALLATION_TOKEN to an installation access token');
    process.exitCode = 2;
    return;
  }
  const org = process.env.GITHUB_ORG || null;
  const callsPerRepo = Number(process.env.GITHUB_CALLS_PER_REPO || 10);

  const rate = await get(token, '/rate_limit');
  if (rate.status !== 200 || !rate.body) {
    console.error(`GET /rate_limit returned ${rate.status}`);
    process.exitCode = 2;
    return;
  }
  const resources = rate.body.resources || {};
  const core = (resources.core || {}).limit;
  const graphql = (resources.graphql || {}).limit;
  console.log(`core ceiling: ${core}/hour, graphql ${graphql}/hour`);

  const inst = await get(token, '/installation/repositories?per_page=1');
  const view = inst.status === 200 ? inst.body : null;
  const covered = reachable(view);
  const selection = selectionOf(view);
  if (view) {
    console.log(`installation: repository_selection=${selection}, ${covered} reachable`);
  }

  let orgRepos = null;
  if (org && selection === 'selected') {
    const o = await get(token, `/orgs/${org}`);
    if (o.status === 200 && o.body) {
      orgRepos = Number(o.body.public_repos || 0) + Number(o.body.total_private_repos || 0);
    } else {
      console.log(`GET /orgs/${org} returned ${o.status}; using the installation size`);
    }
  }

  const [state, detail] = verdict(core, selection, covered, orgRepos, null,
    false, view !== null);
  console.log(`${state}: ${detail}`);
  console.log(`repair: ${repair(state)}`);
  const fits = sustainableRepos(core, callsPerRepo);
  if (fits !== null) {
    console.log(`budget: ${core}/hour serves ${fits} repositories at ${callsPerRepo} call(s) each`);
  }
  console.log(JSON.stringify({
    core_limit: core,
    graphql_limit: graphql,
    repository_selection: selection,
    repositories_covered: covered,
    account_repositories: orgRepos,
    entitlement_is_lower_bound: isLowerBound(null),
    state,
    repositories_supported: fits,
  }, null, 2));
  process.exitCode = ['narrow-installation', 'below-entitlement', 'unauthenticated']
    .includes(state) ? 1 : 0;
}

// Guarded so importing this file from the test runner does not start a run and
// fail the suite even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from github_app_limit_ceiling import (
    classify_ceiling, entitled, is_lower_bound, reachable, repair,
    selection_of, shortfall, sustainable_repos, verdict,
)

WIDE = {"total_count": 400, "repository_selection": "all"}
NARROW = {"total_count": 9, "repository_selection": "selected"}


def test_nothing_scales_below_twenty_of_either_kind():
    assert entitled(0, 0) == 5000
    assert entitled(20, 20) == 5000
    assert entitled(19, 19) == 5000


def test_repositories_and_users_both_add():
    assert entitled(21, 0) == 5050
    assert entitled(0, 21) == 5050
    assert entitled(21, 21) == 5100


def test_the_cap_binds_outside_enterprise_cloud():
    assert entitled(1000, 1000) == 12500
    assert entitled(400, None) == 12500


def test_enterprise_replaces_the_sum_rather_than_extending_it():
    assert entitled(0, 0, enterprise=True) == 15000
    assert entitled(5000, 5000, enterprise=True) == 15000


def test_an_unknown_user_count_makes_the_answer_a_floor():
    assert entitled(30, None) == entitled(30, 0)
    assert entitled(30, 40) > entitled(30, None)
    assert is_lower_bound(None)
    assert not is_lower_bound(0)


def test_each_ceiling_has_a_name():
    assert classify_ceiling(60) == "unauthenticated"
    assert classify_ceiling(5000) == "baseline"
    assert classify_ceiling(7200) == "scaled"
    assert classify_ceiling(12500) == "at-cap"
    assert classify_ceiling(15000) == "enterprise"
    assert classify_ceiling(None) == "unknown"


def test_the_installation_view_is_read_defensively():
    assert selection_of(NARROW) == "selected"
    assert selection_of({"repository_selection": "ALL "}) == "all"
    assert selection_of({}) == "unknown"
    assert selection_of(None) == "unknown"
    assert reachable(WIDE) == 400
    assert reachable({"total_count": None}) is None
    assert reachable(None) is None


def test_a_small_installation_at_five_thousand_is_honest():
    state, detail = verdict(5000, "all", 9)
    assert state == "baseline"
    assert "repair is on the usage side" in detail


def test_a_narrow_installation_on_a_big_account_is_the_finding():
    state, detail = verdict(5000, "selected", 9, account_repos=400)
    assert state == "narrow-installation"
    assert "12500" in detail
    assert "selection is what is capping it" in detail


def test_a_scaled_ceiling_that_matches_its_size_is_not_a_finding():
    assert verdict(entitled(60, None), "all", 60)[0] == "scaled"


def test_the_cap_and_enterprise_are_never_reported_as_shortfalls():
    assert verdict(12500, "selected", 900, account_repos=4000)[0] == "at-cap"
    assert verdict(15000, "all", 4000)[0] == "enterprise"


def test_an_anonymous_ceiling_is_not_an_installation_problem():
    state, _ = verdict(60, "unknown", None, installation_seen=False)
    assert state == "unauthenticated"


def test_a_credential_with_no_installation_view_is_named_as_such():
    state, detail = verdict(5000, "unknown", None, installation_seen=False)
    assert state == "not-an-installation"
    assert "user or Actions credential" in detail


def test_the_shortfall_never_goes_negative():
    assert shortfall(12500, 5000) == 0
    assert shortfall(5000, 12500) == 7500
    assert shortfall(None, 12500) == 0


def test_the_budget_divides_the_ceiling_by_the_loop():
    assert sustainable_repos(12500, 10) == 1250
    assert sustainable_repos(5000, 12) == 416
    assert sustainable_repos(5000, 0) is None


def test_the_repair_for_a_real_ceiling_does_not_suggest_widening():
    assert "widen" not in repair("baseline")
    assert "widen the installation" in repair("narrow-installation")

import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
  classifyCeiling, entitled, isLowerBound, reachable, repair,
  selectionOf, shortfall, sustainableRepos, verdict,
} from './github-app-limit-ceiling.mjs';

const WIDE = { total_count: 400, repository_selection: 'all' };
const NARROW = { total_count: 9, repository_selection: 'selected' };

test('nothing scales below twenty of either kind', () => {
  assert.equal(entitled(0, 0), 5000);
  assert.equal(entitled(20, 20), 5000);
  assert.equal(entitled(19, 19), 5000);
});

test('repositories and users both add', () => {
  assert.equal(entitled(21, 0), 5050);
  assert.equal(entitled(0, 21), 5050);
  assert.equal(entitled(21, 21), 5100);
});

test('the cap binds outside Enterprise Cloud', () => {
  assert.equal(entitled(1000, 1000), 12500);
  assert.equal(entitled(400, null), 12500);
});

test('enterprise replaces the sum rather than extending it', () => {
  assert.equal(entitled(0, 0, true), 15000);
  assert.equal(entitled(5000, 5000, true), 15000);
});

test('an unknown user count makes the answer a floor', () => {
  assert.equal(entitled(30, null), entitled(30, 0));
  assert.ok(entitled(30, 40) > entitled(30, null));
  assert.ok(isLowerBound(null));
  assert.ok(!isLowerBound(0));
});

test('each ceiling has a name', () => {
  assert.equal(classifyCeiling(60), 'unauthenticated');
  assert.equal(classifyCeiling(5000), 'baseline');
  assert.equal(classifyCeiling(7200), 'scaled');
  assert.equal(classifyCeiling(12500), 'at-cap');
  assert.equal(classifyCeiling(15000), 'enterprise');
  assert.equal(classifyCeiling(null), 'unknown');
});

test('the installation view is read defensively', () => {
  assert.equal(selectionOf(NARROW), 'selected');
  assert.equal(selectionOf({ repository_selection: 'ALL ' }), 'all');
  assert.equal(selectionOf({}), 'unknown');
  assert.equal(selectionOf(null), 'unknown');
  assert.equal(reachable(WIDE), 400);
  assert.equal(reachable({ total_count: null }), null);
  assert.equal(reachable(null), null);
});

test('a small installation at five thousand is honest', () => {
  const [state, detail] = verdict(5000, 'all', 9);
  assert.equal(state, 'baseline');
  assert.match(detail, /repair is on the usage side/);
});

test('a narrow installation on a big account is the finding', () => {
  const [state, detail] = verdict(5000, 'selected', 9, 400);
  assert.equal(state, 'narrow-installation');
  assert.match(detail, /12500/);
  assert.match(detail, /selection is what is capping it/);
});

test('a scaled ceiling that matches its size is not a finding', () => {
  assert.equal(verdict(entitled(60, null), 'all', 60)[0], 'scaled');
});

test('the cap and enterprise are never reported as shortfalls', () => {
  assert.equal(verdict(12500, 'selected', 900, 4000)[0], 'at-cap');
  assert.equal(verdict(15000, 'all', 4000)[0], 'enterprise');
});

test('an anonymous ceiling is not an installation problem', () => {
  assert.equal(verdict(60, 'unknown', null, null, null, false, false)[0], 'unauthenticated');
});

test('a credential with no installation view is named as such', () => {
  const [state, detail] = verdict(5000, 'unknown', null, null, null, false, false);
  assert.equal(state, 'not-an-installation');
  assert.match(detail, /user or Actions credential/);
});

test('the shortfall never goes negative', () => {
  assert.equal(shortfall(12500, 5000), 0);
  assert.equal(shortfall(5000, 12500), 7500);
  assert.equal(shortfall(null, 12500), 0);
});

test('the budget divides the ceiling by the loop', () => {
  assert.equal(sustainableRepos(12500, 10), 1250);
  assert.equal(sustainableRepos(5000, 12), 416);
  assert.equal(sustainableRepos(5000, 0), null);
});

test('the repair for a real ceiling does not suggest widening', () => {
  assert.ok(!repair('baseline').includes('widen'));
  assert.match(repair('narrow-installation'), /widen the installation/);
});