@bridge-ds/core 0.2.0 → 0.4.0

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/dist/token-combine.d.ts

@@ -0,0 +1,78 @@
+import { type FlatToken } from './types';
+/** What one change brings: its token files where it started and now, and the token files it edits. */
+export interface CombineSource {
+    number: number;
+    /** Token file texts where the change started (relative to the tokens root). Undefined: the file did not exist. */
+    base: Record<string, string | undefined>;
+    /** Token file texts in the change now. Undefined: the change removes the file. */
+    head: Record<string, string | undefined>;
+    /** Token files the change edits, relative to the tokens root. */
+    files: string[];
+}
+export interface CombineEdit {
+    /** `<file>#<token id>`: the same token in the same file across changes. */
+    key: string;
+    file: string;
+    /** The token's path in the change (its old path when the change removes it). */
+    path: string;
+    change: number;
+    /** The change's version of the token; undefined when the change removes it. */
+    token: FlatToken | undefined;
+}
+export interface ChangeEdits {
+    number: number;
+    edits: CombineEdit[];
+    /** Files that could not be read (not JSON). */
+    problems: string[];
+}
+/** The token edits of one change: every token whose version differs between where the change started and now. */
+export declare function changeEdits(src: CombineSource): ChangeEdits;
+/** One value a conflicting token can take, and the changes that set it. */
+export interface CombineOption {
+    changes: number[];
+    token: FlatToken | undefined;
+}
+/** A token two or more changes set differently: the designer picks one change's value. */
+export interface CombineConflict {
+    key: string;
+    file: string;
+    path: string;
+    /** Distinct values, in the order of the changes. */
+    options: CombineOption[];
+}
+/** The pick of each conflict: the change whose value the combination uses. */
+export type CombinePicks = Record<string, number>;
+export interface Combination {
+    /** Every token file of the latest library, with the combined edits applied (unchanged files as they are). */
+    files: Record<string, string>;
+    /** The changes combined, in order. */
+    included: number[];
+    /** Token values the combination edits (one per token and file: a token edited in light and dark counts twice). */
+    edits: number;
+    /** Tokens the combination edits, by name. */
+    tokens: number;
+    conflicts: CombineConflict[];
+    /** Conflicts without a pick that counts: left at the library's value ('skip') or given the first change's ('first'). */
+    missing: CombineConflict[];
+    /** Token path -> the changes whose value the combination uses for it. */
+    from: Record<string, number[]>;
+    problems: string[];
+}
+/** Tokens that two or more of these changes set differently. */
+export declare function combineConflicts(changes: ChangeEdits[]): CombineConflict[];
+/** The option a pick selects, or null when the picked change is not among them (not picked, or switched off). */
+export declare function pickedOption(c: CombineConflict, picks: CombinePicks): CombineOption | null;
+/** Conflicts that still need a pick. */
+export declare const unpicked: (conflicts: CombineConflict[], picks: CombinePicks) => CombineConflict[];
+/**
+ * The latest library plus the edits of the included changes (all of them by default, in their order). A conflict
+ * uses the picked change's value. Without a pick that counts, `unpicked: 'skip'` (Studio, before opening) leaves the
+ * token at the library's value and lists it in `missing`; `'first'` (the toolbar, when a picked change is switched
+ * off) uses the first included change's value and still lists it.
+ */
+export declare function combineChanges(latest: Record<string, string>, changes: ChangeEdits[], picks?: CombinePicks, opts?: {
+    include?: number[];
+    unpicked?: 'skip' | 'first';
+}): Combination;
+export declare function encodePicks(picks: CombinePicks): string;
+export declare function decodePicks(raw: string | null | undefined): CombinePicks;

package/dist/token-merge.d.ts

@@ -0,0 +1,72 @@
+import { type TokenDocument } from './dtcg-codec';
+import { type FlatToken } from './types';
+/** Which side a conflict keeps: this change ("Keep mine") or the latest library ("Use the library's"). */
+export type MergeSide = 'mine' | 'theirs';
+export interface TokenMergeConflict {
+    /** Stable key for the choice: `<file>#<token id>`. */
+    key: string;
+    /** Token file, relative to the tokens root. */
+    file: string;
+    /** Display path: this change's name, else the library's, else the shared one. */
+    path: string;
+    base?: FlatToken | undefined;
+    mine?: FlatToken | undefined;
+    theirs?: FlatToken | undefined;
+    /** The side that removed the token while the other changed it. Null when both sides kept it. */
+    removedOn: MergeSide | null;
+    /** "Keep mine" by default; null when the token was removed on one side and changed on the other. */
+    defaultChoice: MergeSide | null;
+}
+export interface TokenMergePlan {
+    /** Token files both sides changed, relative to the tokens root. */
+    files: string[];
+    conflicts: TokenMergeConflict[];
+    /** Tokens only this change touched: applied on top of the library as they are. */
+    mineOnly: number;
+    /** Tokens only the library touched: kept as the library has them. */
+    theirsOnly: number;
+    /** Files that could not be read (not JSON): nothing can be merged while there is one. */
+    problems: string[];
+}
+export interface TokenMergeInput {
+    /** File texts at the commit both sides share. Undefined: the file did not exist there. */
+    base: Record<string, string | undefined>;
+    /** File texts in the change. */
+    mine: Record<string, string | undefined>;
+    /** File texts in the latest library. */
+    theirs: Record<string, string | undefined>;
+    /** Token files both sides changed (the others need no merge). */
+    files: string[];
+}
+export type MergeChoices = Record<string, MergeSide | undefined>;
+/** The side that removed a token the other side changed, or null. */
+export declare function removedSide(c: {
+    base?: unknown;
+    mine?: unknown;
+    theirs?: unknown;
+}): MergeSide | null;
+/** "Keep mine" by default, except for a token removed on one side and changed on the other: no default there. */
+export declare const defaultChoiceFor: (c: {
+    base?: unknown;
+    mine?: unknown;
+    theirs?: unknown;
+}) => MergeSide | null;
+/** What both sides did to the token files they both changed, and which tokens need a decision. */
+export declare function planTokenMerge(input: TokenMergeInput): TokenMergePlan;
+/** The side a conflict keeps: the designer's pick, else its default (null: still to pick). */
+export declare const choiceFor: (c: TokenMergeConflict, choices: MergeChoices) => MergeSide | null;
+/** Conflicts that still need a pick: removed on one side, changed on the other, and not decided yet. */
+export declare function missingChoices(plan: Pick<TokenMergePlan, 'conflicts'>, choices: MergeChoices): TokenMergeConflict[];
+/** Puts this change's version of a token into the library's file: its value, type, description and extensions. Also used by token-combine. */
+export declare function takeMine(doc: TokenDocument, mine: FlatToken | undefined, existing: FlatToken | undefined): boolean;
+export interface TokenMergeResult {
+    /** Merged text per file (relative to the tokens root); null when the merged file holds no token and is removed. */
+    files: Record<string, string | null>;
+    /** How many conflicts kept each side. */
+    kept: Record<MergeSide, number>;
+}
+/**
+ * The merged token files: the latest library's text, plus every token only this change touched, plus each conflict
+ * as chosen. Throws when a file could not be read or a conflict still needs a pick.
+ */
+export declare function applyTokenMerge(input: TokenMergeInput, choices: MergeChoices): TokenMergeResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/core",
-  "version": "0.2.0",
+  "version": "0.4.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",