@bridge-ds/core 0.2.0 → 0.3.0

package/dist/node/index.js

@@ -2,7 +2,7 @@ import { execFile } from "node:child_process";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve, relative, dirname, sep, posix } from "node:path";
-import { a as assertSafeBranch, c as collectHistory, p as packageDirCandidates, b as parseChangelog, m as mergeReleases, r as releasesFromTags, d as buildReport, e as prNumberFromSubject, l as loadConfig, h as hashSpec, C as COMPONENT_SPECS_VERSION, f as CONFIG_FILE, g as layoutOptions, v as variantKeyOf, i as buildTokenSet, t as tokenCssVar, j as iconComponentName, k as COLOR_FIELDS } from "../component-spec-B0V_D3gM.js";
+import { a as assertSafeBranch, c as collectHistory, p as packageDirCandidates, b as parseChangelog, m as mergeReleases, r as releasesFromTags, d as buildReport, e as prNumberFromSubject, l as loadConfig, h as hashSpec, C as COMPONENT_SPECS_VERSION, f as CONFIG_FILE, g as layoutOptions, v as variantKeyOf, i as buildTokenSet, t as tokenCssVar, j as iconComponentName, k as COLOR_FIELDS } from "../component-spec-IRFGJ7XK.js";
 import { s as selectTokenFiles, g as globToRegExp, L as LayeredTokenSet } from "../layered-DGate4nv.js";
 import { statSync, readFileSync, existsSync, writeFileSync, readdirSync } from "node:fs";
 import { n as isAuditable, x as planCssFixes, c as DesignSystemIndex, g as buildAuditReport, i as compareWithBaseline, a as AUDIT_IGNORE_DIRS } from "../report-tNzTriGF.js";

package/dist/previews-github.d.ts

@@ -0,0 +1,22 @@
+import type { BridgeConfig } from './config';
+import type { GitHubClient } from './github-client';
+import { type BranchPreview, type PreviewApps } from './previews';
+export interface BranchPreviewOptions {
+    /** Branch and head commit when the caller knows them (skips reading the pull request). */
+    branch?: string | undefined;
+    sha?: string | undefined;
+    /** The pull request's comments when the caller already read them (skips one read). */
+    comments?: {
+        body?: string | null | undefined;
+    }[] | undefined;
+}
+/**
+ * The preview of each app configured in `previews.apps` for a pull request (by number) or a commit (by sha): the URL
+ * Vercel reports (deployments, then commit statuses, then its PR comment), the template only when Vercel cannot have
+ * shortened it, and whether the build of that commit is ready. A failed read leaves that source out, never throws for it.
+ */
+export declare function branchPreviewUrls(gh: GitHubClient, ref: number | string, config: Pick<BridgeConfig, 'previews'> | {
+    previews?: {
+        apps?: PreviewApps | undefined;
+    } | undefined;
+} | undefined, opts?: BranchPreviewOptions): Promise<BranchPreview[]>;

package/dist/previews.d.ts

@@ -74,6 +74,108 @@ export interface PreviewCommentInput {
     apps: PreviewApps;
     /** An exploration (`explore/*` branch or `exploration` label): staging only, never merged as is (docs/EXPLORATIONS.md). */
     exploration?: boolean | undefined;
+    /**
+     * The previews as Vercel reports them (`resolveBranchPreviews` over the deployments, statuses and the Vercel
+     * comment). Without it, only template URLs Vercel cannot have shortened are written.
+     */
+    previews?: BranchPreview[] | undefined;
 }
 /** The sticky PR comment: install commands for each package, then the per-branch previews. Markdown, no HTML. */
 export declare function previewComment(input: PreviewCommentInput): string;
+/** What the sticky comment says about installing a snapshot, read back by tools (plugin, Studio). */
+export interface PreviewCommentInstall {
+    /** The command of the first ```sh block, exactly as the workflow wrote it. Null when publishing failed. */
+    command: string | null;
+    /** The commit the snapshot was built from (`Snapshot of \`1a2b3c4\``), or null when the comment does not say. */
+    sha7: string | null;
+    /** Where the snapshots live, from the command's URLs. */
+    source: 'pkg.pr.new' | 'release' | 'other' | 'none';
+}
+/**
+ * The install command of a `<!-- bridge-branch-preview -->` comment: the first ```sh block, its lines joined (a
+ * trailing `\` continues a line). Null when the body is not that comment or has no command (the publish failed).
+ * This is the command that works: pkg.pr.new when the workflow published there, the prerelease tarballs otherwise.
+ */
+export declare function installCommandFromPreviewComment(body: string | null | undefined): string | null;
+/** Reads a sticky preview comment back: its command, the commit it was built from, where the snapshots live. */
+export declare function readPreviewComment(body: string | null | undefined): PreviewCommentInstall | null;
+/** The sticky preview comment among a pull request's comments (the last one, if a run ever posted twice). */
+export declare function findPreviewComment<T extends {
+    body?: string | null | undefined;
+}>(comments: T[]): T | undefined;
+/** Where a preview URL comes from, most trusted first. */
+export type PreviewUrlSource = 'deployment' | 'status' | 'vercel-comment' | 'template';
+/** Whether the preview of the latest commit can be opened. `unknown` when only the template says where it is. */
+export type PreviewState = 'ready' | 'building' | 'failed' | 'unknown';
+export interface BranchPreview {
+    app: keyof PreviewApps;
+    label: string;
+    /** Null when nothing reports it yet and the template cannot be trusted (a host label over 63 characters). */
+    url: string | null;
+    state: PreviewState;
+    source: PreviewUrlSource | null;
+}
+/** A GitHub deployment with its latest status, as `GitHubClient.listDeployments` returns it. */
+export interface DeploymentLike {
+    environment: string;
+    state?: string | null | undefined;
+    environmentUrl?: string | null | undefined;
+}
+/** A commit status (`GET /commits/{sha}/statuses`), newest first like GitHub returns them. */
+export interface CommitStatusLike {
+    context: string;
+    state: string;
+    target_url?: string | null | undefined;
+}
+/** One project of the Vercel bot comment. */
+export interface VercelCommentProject {
+    name: string;
+    /** https URL of the branch alias, as Vercel built it (shortened when long). */
+    previewUrl: string | null;
+    /** `DEPLOYED`, `PENDING`, `BUILDING`, `IGNORED`, `FAILED`... as Vercel writes it. */
+    status: string | null;
+}
+/** True for the comment the Vercel GitHub app posts (and edits) on a pull request. */
+export declare const isVercelComment: (body: string | null | undefined) => boolean;
+/**
+ * The projects of a Vercel bot comment, from its hidden header `[vc]: #<hash>:<base64 JSON>` (projects[].name and
+ * previewUrl). Null when the body is not that comment or the header does not decode.
+ */
+export declare function parseVercelComment(body: string | null | undefined): VercelCommentProject[] | null;
+/** The Vercel bot comment among a pull request's comments (the last one, if there were ever two). */
+export declare function findVercelComment<T extends {
+    body?: string | null | undefined;
+}>(comments: T[]): T | undefined;
+/**
+ * The app (`docs`, `storybook`, `admin`) a Vercel project serves, from the host its template starts with: project
+ * `bridge-admin` serves the app whose template host starts with `bridge-admin-git-` (Vercel's branch alias shape),
+ * else with `bridge-admin-` when only one template does. Null when no template names it.
+ */
+export declare function appForProject(project: string, apps: PreviewApps): keyof PreviewApps | null;
+/** The project a deployment environment or a status context names: `Preview – bridge-admin` -> `bridge-admin`. */
+export declare function projectOfLabel(label: string): string | null;
+export interface BranchPreviewSources {
+    /** GitHub deployments of the head commit, each with its latest status. */
+    deployments?: DeploymentLike[] | undefined;
+    /** Commit statuses of the head commit, newest first. */
+    statuses?: CommitStatusLike[] | undefined;
+    /** The pull request's comments (the Vercel bot comment is read from them). */
+    comments?: {
+        body?: string | null | undefined;
+    }[] | undefined;
+}
+/**
+ * The preview of each configured app, real URL first: a GitHub deployment's environment URL, then a Vercel commit
+ * status pointing at the deployment (not at the inspector), then the Vercel bot comment, and the config template only
+ * when its host labels fit in 63 characters (else Vercel shortened it: url null until a real source reports it).
+ * The state comes from the freshest signal: commit status, then deployment, then the comment.
+ */
+export declare function resolveBranchPreviews(apps: PreviewApps, ctx: PreviewContext, sources?: BranchPreviewSources): BranchPreview[];
+/** The previews that have a URL, as links (`{ app, label, url }`), in the stable app order. */
+export declare const previewLinksOf: (previews: BranchPreview[]) => {
+    app: keyof PreviewApps;
+    label: string;
+    url: string;
+}[];
+/** True when every configured app has its URL and a finished build (ready or failed): polling can stop. */
+export declare const previewsSettled: (previews: BranchPreview[]) => boolean;

package/dist/protection-github.d.ts

@@ -0,0 +1,25 @@
+import { type GitHubClient } from './github-client';
+import { type ProtectionOptions, type ProtectionState, type Ruleset } from './protection';
+/**
+ * The protection of `defaultBranch`. Rulesets are listed (read access is enough), then read one by one for their
+ * rules; classic branch protection is read too. Whatever cannot be read counts as unknown, never as unprotected.
+ */
+export declare function loadProtection(client: GitHubClient, defaultBranch: string): Promise<ProtectionState>;
+/** The checks to require: the default branch's latest check runs, kept to those the last merged pull request ran. */
+export declare function loadRequiredChecks(client: GitHubClient, defaultBranch: string): Promise<string[]>;
+/**
+ * Turns protection on: creates the Bridge ruleset, or replaces it when one with its name exists (Complete
+ * protection). Needs a token with admin on the repository; GitHub's refusal is thrown as a GitHubError.
+ */
+export declare function protectLibrary(client: GitHubClient, defaultBranch: string, opts?: Partial<ProtectionOptions> & {
+    state?: ProtectionState;
+}): Promise<Ruleset>;
+/** True when GitHub refused the ruleset because of the repository's plan, not the token. */
+export declare const isPlanRefusal: (err: unknown) => boolean;
+/** Where rulesets are managed on GitHub. */
+export declare const rulesSettingsUrl: (owner: string, repo: string) => string;
+/**
+ * The one sentence for a refused "Protect the library": the plan, the token's permission, or admin access.
+ * Null for any other failure (the caller shows GitHub's message).
+ */
+export declare function protectRefusal(err: unknown): string | null;

package/dist/protection.d.ts

@@ -0,0 +1,139 @@
+/** A ruleset rule as GitHub returns and accepts it. */
+export interface RulesetRule {
+    type: string;
+    parameters?: Record<string, unknown>;
+}
+export interface RulesetBypassActor {
+    actor_id: number | null;
+    actor_type: 'RepositoryRole' | 'Team' | 'Integration' | 'OrganizationAdmin' | 'DeployKey';
+    bypass_mode: 'always' | 'pull_request';
+}
+/** A repository ruleset (GET /repos/{o}/{r}/rulesets/{id}). The list endpoint leaves out `rules`. */
+export interface Ruleset {
+    id?: number;
+    name: string;
+    target?: 'branch' | 'tag' | 'push' | string;
+    enforcement: 'active' | 'evaluate' | 'disabled' | string;
+    conditions?: {
+        ref_name?: {
+            include?: string[];
+            exclude?: string[];
+        };
+    } | null;
+    rules?: RulesetRule[];
+    bypass_actors?: RulesetBypassActor[];
+    /** Where the ruleset is edited on GitHub. */
+    html_url?: string;
+    _links?: {
+        html?: {
+            href?: string;
+        };
+    };
+}
+/** The body of POST /repos/{o}/{r}/rulesets. */
+export interface RulesetPayload {
+    name: string;
+    target: 'branch';
+    enforcement: 'active';
+    conditions: {
+        ref_name: {
+            include: string[];
+            exclude: string[];
+        };
+    };
+    rules: RulesetRule[];
+    bypass_actors: RulesetBypassActor[];
+}
+/**
+ * Classic branch protection (GET /repos/{o}/{r}/branches/{b}/protection), the fields Bridge reads.
+ * `null` means the branch has none; `undefined` means it could not be read (no token, no admin access).
+ */
+export interface ClassicProtection {
+    required_pull_request_reviews?: {
+        required_approving_review_count?: number;
+    } | null;
+    required_status_checks?: {
+        contexts?: string[];
+        checks?: {
+            context: string;
+        }[];
+    } | null;
+    allow_force_pushes?: {
+        enabled: boolean;
+    } | null;
+    allow_deletions?: {
+        enabled: boolean;
+    } | null;
+}
+/** What protecting the library takes, in the order Studio names them. */
+export type ProtectionPart = 'review' | 'checks' | 'history' | 'deletion';
+export declare const PROTECTION_PARTS: readonly ProtectionPart[];
+export type ProtectionKind = 'protected' | 'partial' | 'unprotected' | 'unknown';
+export interface ProtectionState {
+    kind: ProtectionKind;
+    /** Parts not enforced on the default branch (empty when protected; every part when unprotected or unknown). */
+    missing: ProtectionPart[];
+    /** The Bridge ruleset (by name), when one exists, active or not: "Complete protection" updates it in place. */
+    bridgeRulesetId?: number;
+    /** Where to see the rule that protects the branch on GitHub, when one does. */
+    url?: string;
+}
+/** The name Bridge gives its ruleset. Bridge finds it again by this name. */
+export declare const protectionRulesetName: (defaultBranch: string) => string;
+/** GitHub's built-in repository role id for "Admin", used in bypass_actors. */
+export declare const ADMIN_ROLE_ID = 5;
+export interface ProtectionOptions {
+    /** Check names that must pass before a merge (see requiredCheckNames). Empty: no checks rule. */
+    checks: string[];
+    /** Approvals a pull request needs. Never below 1. */
+    approvals: number;
+    /** Let repository admins merge a pull request without its approvals (the owner override). */
+    adminBypass: boolean;
+}
+/**
+ * The ruleset that protects the library. Choices:
+ * - Target `~DEFAULT_BRANCH`, not a branch name: it follows a rename of the default branch.
+ * - `deletion` and `non_fast_forward`: nobody deletes the default branch or rewrites its history.
+ * - `pull_request` with at least 1 approval: every change goes through a reviewed pull request, direct pushes are
+ *   refused whoever pushes. Stale approvals are dismissed on a new push, so what was approved is what merges.
+ *   Code owner review and "approval of the most recent push" stay off: CODEOWNERS often holds placeholders, and a
+ *   team of two must still be able to ship.
+ * - `required_status_checks`: the CI jobs that ran on recent pull requests must pass. Not strict (the branch does
+ *   not have to be up to date), which keeps merges from queueing behind each other.
+ * - Bypass: repository admins in `pull_request` mode only. They keep the owner override (merge a pull request
+ *   whose approvals are missing) but cannot push to the default branch either.
+ */
+export declare function protectionRuleset(config: {
+    repo?: {
+        defaultBranch?: string;
+    } | undefined;
+} | null | undefined, opts: ProtectionOptions): RulesetPayload;
+/** Minimal check run shape (github-client CheckRun fits). `app` is the GitHub App slug when known. */
+export interface CheckRunLike {
+    name: string;
+    status?: string;
+    conclusion: string | null;
+    app?: string | undefined;
+}
+/**
+ * The check names to require, read from the repository's own CI, never hardcoded: the check runs of the default
+ * branch's latest commit, without Vercel (deploy previews, not tests) and without skipped ones. When the head of a
+ * recent pull request is given, only checks that also ran there are kept: a job that runs on pushes to the default
+ * branch only (a release job) never reports on a pull request, and requiring it would block every merge.
+ */
+export declare function requiredCheckNames(defaultBranchRuns: CheckRunLike[], pullRequestRuns?: CheckRunLike[]): string[];
+/** True when a branch ruleset's conditions cover the default branch. */
+export declare function rulesetTargetsDefault(ruleset: Ruleset, defaultBranch: string): boolean;
+/**
+ * Whether the default branch is protected, from full rulesets (with `rules`; null when they could not be read) and
+ * classic branch protection (null when the branch has none, undefined when it could not be read).
+ * - protected: review, checks, no history rewrite and no deletion are all enforced.
+ * - partial: some of them are.
+ * - unprotected: none of them, and both sources were read.
+ * - unknown: nothing could be read, or nothing was found in one source while the other could not be read.
+ */
+export declare function protectionState(rulesets: Ruleset[] | null | undefined, branchProtection: ClassicProtection | null | undefined, defaultBranch: string): ProtectionState;
+/** Plain words for each part, for designers: no "ruleset", "branch" or "force push". */
+export declare const PROTECTION_PART_PHRASE: Record<ProtectionPart, string>;
+/** The one sentence Studio, the CLI and the MCP server show for a protection state. */
+export declare function protectionSentence(state: ProtectionState): string;

package/dist/requests-github.d.ts

@@ -0,0 +1,21 @@
+import { GitHubClient } from './github-client';
+export interface RequestExplorationLink {
+    number: number;
+    branch: string;
+    /** Who is now on it, when someone was assigned in the same step. */
+    assignees: string[];
+    /** Sentences about the parts that did not go through (label refused): the link itself holds. */
+    warnings: string[];
+}
+/**
+ * Links a request to an exploration branch, the way `bridge request create --exploration` files one: the hidden block
+ * gets `exploration`, the issue gets the `exploration` label, and whoever starts the exploration is assigned, so the
+ * request reads "in progress" everywhere. Implementing it then happens on that branch (`request implement --branch`).
+ */
+export declare function linkRequestToExplorationOnGitHub(gh: GitHubClient, n: number, branch: string, opts?: {
+    assignee?: string | null;
+}): Promise<RequestExplorationLink>;
+/** Assigns someone to a request. Throws when GitHub does not keep the assignee (no access to the repository). */
+export declare function assignRequestOnGitHub(gh: GitHubClient, n: number, login: string): Promise<string[]>;
+/** Declines a request: the reason as a comment the requester is notified of, then the issue closed as not planned. */
+export declare function declineRequestOnGitHub(gh: GitHubClient, n: number, reason: string, by?: string | null): Promise<void>;

package/dist/requests.d.ts

@@ -1,4 +1,4 @@
-export type RequestKind = 'new-component' | 'new-variant' | 'prop-change' | 'visual' | 'token-binding' | 'bug' | 'other';
+export type RequestKind = 'new-component' | 'new-variant' | 'prop-change' | 'structure' | 'visual' | 'token-binding' | 'bug' | 'other';
 export type RequestSource = 'figma' | 'studio' | 'cli' | 'mcp';
 export type RequestStatus = 'requested' | 'in-progress' | 'done' | 'declined';
 export declare const REQUEST_KINDS: {
@@ -22,6 +22,11 @@ export interface ComponentChangeRequest {
     title: string;
     /** What and why, in the requester's words. */
     summary: string;
+    /**
+     * What changed for developers in one sentence ("Icon added after the label in primary sm: Pencil, 16px"): written
+     * by Claude from the before and after images, or drafted from the detected changes. Optional.
+     */
+    line?: string | undefined;
     changes: RequestChange[];
     /** Where the design lives, when it comes from Figma. */
     figma?: {
@@ -57,6 +62,16 @@ export declare function composeRequestIssue(r: ComponentChangeRequest, opts?: {
 }): RequestIssue;
 /** The request inside an issue body, or undefined when the body has no valid Bridge block. */
 export declare function parseRequestIssue(body: string | null | undefined): ComponentChangeRequest | undefined;
+/**
+ * The issue body with the request linked to an exploration branch: the hidden block gets `exploration` (what the
+ * Explorations view, the MCP server and the CLI read) and the readable part says where to implement it. The rest of the
+ * body stays as people wrote it. Undefined when the body has no Bridge block (nothing to link).
+ */
+export declare function withRequestExploration(body: string | null | undefined, branch: string): string | undefined;
+/** Problems with a decline reason, as sentences that say how to fix them. */
+export declare function declineReasonProblems(reason: string): string[];
+/** The comment posted on a declined request: who declined it and why, in the decliner's words. */
+export declare function declineComment(reason: string, by?: string | null): string;
 /**
  * Where a request stands: open with no linked pull request = requested; open with an open linked pull request =
  * in progress; closed as completed or by a merged pull request = done; closed otherwise = declined.

package/dist/rights.d.ts

@@ -0,0 +1,63 @@
+import type { Owners } from './config';
+import { type TeamState, type TeamStates } from './teams';
+/** An owner group from `governance.owners`. */
+export type OwnerGroup = 'design' | 'tech';
+export declare const OWNER_GROUPS: readonly OwnerGroup[];
+/** The three rights, each held by one or more owner groups. */
+export interface Rights {
+    approveDesign: OwnerGroup[];
+    approveTech: OwnerGroup[];
+    ship: OwnerGroup[];
+}
+export type Right = keyof Rights;
+export declare const RIGHTS: readonly Right[];
+/** Plain names of each right, for Settings and the gate messages. "Ship" means publish to the products. */
+export declare const RIGHT_LABEL: Record<Right, string>;
+export declare const DEFAULT_RIGHTS: Rights;
+/** Rights with every missing entry filled from DEFAULT_RIGHTS, groups deduplicated in design, tech order. */
+export declare function normalizeRights(input: Partial<Record<Right, readonly string[]>> | null | undefined): Rights;
+/** Problems in a raw `governance.rights` value, in the words loadConfig reports. Empty: valid. */
+export declare function rightsProblems(raw: unknown): string[];
+/** The entries (people and teams) holding a right: the union of the owner lists of its groups. Empty when those lists are empty. */
+export declare function holdersOf(right: Right, owners: Owners, rights: Rights | null | undefined): string[];
+/**
+ * Owner lists to count approvals against (summarizeApprovals): who may approve design, who may approve tech.
+ * Without `rights`, the owner lists as they are.
+ */
+export declare function approverLists(owners: Owners, rights: Rights | null | undefined, teams?: TeamStates | null): Owners;
+/** approverLists before team expansion: the entries as the config names them, for sentences. */
+export declare function approverEntries(owners: Owners, rights: Rights | null | undefined): Owners;
+/** Who may ship, or null when nobody is singled out (no `rights`, or its groups list no logins): anyone with write access. */
+export interface ShipPolicy {
+    /** Logins allowed to ship: people, and team members once read. A team not read keeps its "@org/slug" key. */
+    logins: string[];
+    /** Owner groups holding the right, for the sentence ("the tech owner", "a design or tech owner"). */
+    groups: OwnerGroup[];
+    /** The entries as the config names them (people and teams), for the sentence. Absent: `logins`. */
+    entries?: string[];
+    /** Team states known when the policy was built, for the sentence ("@acme/design (4 people)"). */
+    teams?: TeamStates;
+}
+/**
+ * Who may ship. With `teams` (TeamDirectory.resolve), team members count; a team that cannot be read still holds
+ * the right, so the policy is never dropped to "anyone with write access" because a team was not read.
+ */
+export declare function shipPolicy(owners: Owners, rights: Rights | null | undefined, teams?: TeamStates | null): ShipPolicy | null;
+/** Teams in a ship policy that could not be read: the gate names them with the fix. */
+export declare function unreadableShipTeams(policy: ShipPolicy | null | undefined): TeamState[];
+/** Whether `login` may ship. No policy: yes (GitHub write access still decides). */
+export declare function canShip(login: string | null | undefined, policy: ShipPolicy | null | undefined): boolean;
+/** "the tech owner", "the design owner", "a design or tech owner". */
+export declare function groupsPhrase(groups: readonly OwnerGroup[]): string;
+/** The sentence a blocked viewer reads: "Only the tech owner can ship this." */
+/** Teams are named as teams, with their size when known: "Only the tech owner can ship this (@acme/web (4 people))." */
+export declare function whoCanShipSentence(policy: ShipPolicy): string;
+/** Visual before and after: on every pull request that touches tokens or components, or only when asked. */
+export type VisualImpactMode = 'auto' | 'on-demand';
+export interface VisualImpactConfig {
+    mode: VisualImpactMode;
+}
+export declare const DEFAULT_VISUAL_IMPACT: VisualImpactConfig;
+/** Label that asks the visual impact workflow to run in on-demand mode. */
+export declare const VISUAL_CHECK_LABEL = "visual-check";
+export declare function visualImpactProblems(raw: unknown): string[];

package/dist/teams.d.ts

@@ -0,0 +1,149 @@
+import type { Owners } from './config';
+export type OwnerEntry = {
+    kind: 'person';
+    login: string;
+} | {
+    kind: 'team';
+    org: string;
+    slug: string;
+};
+/** A person or a team, or null when `raw` is neither. Accepts a leading @ on both. */
+export declare function parseOwnerEntry(raw: string): OwnerEntry | null;
+/** "@acme/design" for a team, "peterbono" for a person: the form Bridge writes back to bridge.config.json. */
+export declare function formatOwnerEntry(e: OwnerEntry): string;
+/** Whether a raw entry names a team. */
+export declare const isTeamEntry: (raw: string) => boolean;
+/** Case-insensitive key of a team: "@acme/design". */
+export declare const teamKey: (org: string, slug: string) => string;
+/** Key of a raw team entry, undefined for a person or a malformed entry. */
+export declare function teamKeyOf(raw: string): string | undefined;
+/**
+ * Problems in the raw owner lists, in the words loadConfig reports. Each malformed entry is named with the two
+ * accepted forms, so the fix is in the message.
+ */
+export declare function ownerEntryProblems(raw: unknown): string[];
+/** Why a team's members cannot be read, each with its own fix (teamUnreadableMessage). */
+export type TeamUnreadableReason = 
+/** The repository owner (or the org named) is a personal account: GitHub teams only exist in organizations. */
+'personal-account'
+/** The token works but may not read the organization's teams (classic: read:org; fine-grained: Members, read). */
+ | 'missing-permission'
+/** No token, or GitHub refused it: GitHub never shows team members anonymously. */
+ | 'no-token'
+/** GitHub says the team does not exist, or hides it from this token. */
+ | 'not-found'
+/** GitHub did not answer (network, rate limit, server error). */
+ | 'unreachable';
+export interface TeamRef {
+    /** "@acme/design", lowercase. */
+    key: string;
+    org: string;
+    slug: string;
+}
+export type TeamState = (TeamRef & {
+    status: 'ok';
+    members: string[];
+}) | (TeamRef & {
+    status: 'unreadable';
+    reason: TeamUnreadableReason;
+    message: string;
+});
+/** Team states by key ("@acme/design"). */
+export type TeamStates = Record<string, TeamState>;
+/** The one sentence that says why a team cannot be read and how to fix it. */
+export declare function teamUnreadableMessage(team: {
+    org: string;
+    slug: string;
+}, reason: TeamUnreadableReason): string;
+/** Distinct teams named in the owner lists, in order. */
+export declare function teamsIn(owners: Partial<Owners> | readonly string[]): TeamRef[];
+/**
+ * Logins of a list of entries: people as they are, a readable team as its members. An unreadable team, or one not
+ * resolved yet, stays as its "@org/slug" key: never empty, never matching a login.
+ */
+export declare function expandEntries(entries: readonly string[], teams?: TeamStates | null): string[];
+/** Both owner lists expanded (expandEntries). */
+export declare function expandOwners(owners: Owners, teams?: TeamStates | null): Owners;
+/** How an entry reads in a sentence: "@peterbono", "@acme/design (4 people)", "@acme/design" while unknown. */
+export declare function entryLabel(raw: string, teams?: TeamStates | null): string;
+/**
+ * The entries to name for a set of logins (someone who can still act): each person among them, each team with a
+ * member among them, and each team whose members are unknown (it may hold one). Labels as entryLabel.
+ */
+export declare function entriesFor(entries: readonly string[], logins: readonly string[], teams?: TeamStates | null): string[];
+/** Teams that could not be read, in order. */
+export declare function unreadableTeams(teams: TeamStates | null | undefined): Extract<TeamState, {
+    status: 'unreadable';
+}>[];
+/** What TeamDirectory needs from a GitHub client. GitHubClient implements it. */
+export interface TeamReader {
+    /** Whether a token is sent: GitHub never lists team members anonymously. */
+    readonly hasToken: boolean;
+    /** Every member login of a team (GET /orgs/{org}/teams/{slug}/members, all pages). */
+    listTeamMembers(org: string, slug: string): Promise<string[]>;
+    /** A user's membership of a team (GET /orgs/{org}/teams/{slug}/memberships/{user}): "active", "pending", or null when not a member. */
+    getTeamMembership(org: string, slug: string, login: string): Promise<'active' | 'pending' | null>;
+    /** "User" or "Organization" (GET /users/{login}), null when unknown. */
+    getAccountType(login: string): Promise<'User' | 'Organization' | null>;
+    /** The organization's teams the token can see (GET /orgs/{org}/teams, all pages). */
+    listOrgTeams(org: string): Promise<{
+        slug: string;
+        name: string;
+    }[]>;
+}
+export interface TeamDirectoryOptions {
+    /** How long a team read is kept, in ms. Default 5 minutes. */
+    ttlMs?: number;
+    now?: () => number;
+}
+/** Whether one person may act through a list of entries, and which teams could not be checked. */
+export interface MembershipResult {
+    member: boolean;
+    /** Teams whose membership could not be read: when `member` is false, the answer may be wrong for them. */
+    unreadable: Extract<TeamState, {
+        status: 'unreadable';
+    }>[];
+}
+/**
+ * Expands teams to logins through a TeamReader, with a cache: each team is read once per `ttlMs`, concurrent reads
+ * of one team share the request. Every failure becomes an "unreadable" state with its reason.
+ */
+export declare class TeamDirectory {
+    private readonly reader;
+    private readonly teams;
+    private readonly accounts;
+    private readonly memberships;
+    private readonly ttl;
+    private readonly now;
+    constructor(reader: TeamReader, opts?: TeamDirectoryOptions);
+    private accountType;
+    /** The reason a read of `org` failed, as a state. A 404 on a personal account says so; a 403 is a missing permission. */
+    private failure;
+    /** Members of one team, or why they cannot be read. Cached. */
+    team(org: string, slug: string): Promise<TeamState>;
+    /** Every team named in the owner lists, read in parallel. Empty object when no team is named (no request). */
+    resolve(owners: Partial<Owners> | readonly string[]): Promise<TeamStates>;
+    /**
+     * Whether `login` is an active member of one team: from the cached member list when there is one, else one
+     * membership read (GET /orgs/{org}/teams/{slug}/memberships/{user}). An unreadable team returns its state.
+     */
+    isMember(org: string, slug: string, login: string): Promise<boolean | TeamState>;
+    /**
+     * Whether `login` holds a right given to `entries` (people and teams): a person entry matches directly, a team
+     * through its membership. Teams are only read when no person entry matches.
+     */
+    memberOfAny(entries: readonly string[], login: string): Promise<MembershipResult>;
+    /** The organization's teams for a picker, or why they cannot be listed (a personal account has none). */
+    orgTeams(org: string): Promise<{
+        status: 'ok';
+        teams: {
+            slug: string;
+            name: string;
+        }[];
+    } | {
+        status: 'unreadable';
+        reason: TeamUnreadableReason;
+    }>;
+    /** Drops every cached read (after the token changes). */
+    clear(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Bridge core: bridge.config.json, DTCG token loading (tiers and layered modes), alias resolution, WCAG contrast, diffs, minimal-diff edits, PR body, the shared risk tier classifier, changesets and a fetch-based GitHub client. No Figma API, no DOM; Node-only helpers (git, reading a product folder) under @bridge-ds/core/node; the adoption audit under @bridge-ds/core/audit.",
   "license": "MIT",