@bridge-ds/core 0.8.0 → 0.10.0

package/dist/prod-branch-github.d.ts

@@ -0,0 +1,160 @@
+import type { ChangesMode } from './config';
+import { type ExplorationSettings } from './explorations-github';
+import { type GitHubClient, type PullRequestSummary } from './github-client';
+import { type ProductConfig } from './products';
+import { productBranchSentence, type LibraryBranchPlan, type LibraryLink, type LinkStatus, type MissingPiece, type PiecesRecord, type LibraryPreviewState, type ProductBranchRef } from './prod-branch';
+import { type RequestSource } from './requests';
+/** At most this many product files are read per check (two reads each). */
+export declare const PIECES_FILE_LIMIT = 40;
+type Pull = PullRequestSummary & {
+    body: string;
+    mergeable: boolean | null;
+    requestedReviewers: string[];
+};
+export interface ProductBranchRead {
+    pull: Pull;
+    product: ProductConfig;
+    /** The product's changed files, their texts at the branch start (merge base with main) and at its head. */
+    files: {
+        path: string;
+        before: string | null;
+        after: string | null;
+    }[];
+    /** Product files left unread past the limit. */
+    skipped: number;
+    record: PiecesRecord | undefined;
+}
+/**
+ * Reads a product branch for the check: the pull request, its product, and the product files it changes with their
+ * text before and after (two reads per file, up to PIECES_FILE_LIMIT files).
+ */
+export declare function readProductBranchOnGitHub(gh: GitHubClient, pr: number, opts: {
+    products: readonly ProductConfig[];
+}): Promise<ProductBranchRead>;
+/** Saves a check in the product branch body, keeping the library branches already opened for its pieces. */
+export declare function recordPiecesOnGitHub(gh: GitHubClient, pr: number, check: {
+    pieces: MissingPiece[];
+    fixes: number;
+    headSha?: string | undefined;
+    checkedAt?: string | undefined;
+}): Promise<PiecesRecord>;
+export interface PreviewMerge {
+    status: 'merged' | 'up-to-date' | 'conflict';
+    sha: string | null;
+    said: string;
+}
+/**
+ * The product branch uses the library branch's preview: Bridge merges the library branch into it, so the product
+ * preview deploy and anyone working on the branch get the real library change. A conflict is left to a developer.
+ */
+export declare function useLibraryPreviewOnGitHub(gh: GitHubClient, input: {
+    productBranch: string;
+    libraryBranch: string;
+    libraryNumber: number;
+}): Promise<PreviewMerge>;
+export interface OpenLibraryBranchInput {
+    /** The product branch (pull request number). */
+    pr: number;
+    /** The piece id, from the recorded check. */
+    piece: string;
+    /** Branch library work starts from (the default branch). */
+    base: string;
+    products: readonly ProductConfig[];
+    /** Previews and snapshot packages for a library exploration. */
+    exploration: Pick<ExplorationSettings, 'packages' | 'apps'>;
+    /**
+     * Opens the token change of a token piece (planTokenProposal + writeTokenProposalOnGitHub where the caller has the
+     * token files and contrast pairs). Without it a token piece is refused. In suggest mode (`ctx.mode`), it files a
+     * suggestion instead (suggestTokenProposalOnGitHub with `neededBy: plan.neededBy`) and returns its result: a result
+     * with `status: 'suggested'` is linked as a suggestion, anything else as a token change pull request.
+     */
+    writeTokens?: ((plan: Extract<LibraryBranchPlan, {
+        kind: 'token-change';
+    }>, ctx: {
+        mode: ChangesMode;
+    }) => Promise<LibraryTokenWrite>) | undefined;
+    /** Who opens it, and the AI agent behind it ("claude"). */
+    openedBy?: string | undefined;
+    agent?: string | undefined;
+    source?: RequestSource | undefined;
+    /** Merge the new library branch into the product branch when it already changes something (default true). */
+    usePreview?: boolean | undefined;
+    dryRun?: boolean | undefined;
+    /**
+     * "direct" (default here, so existing callers keep their behaviour): a token piece opens a pull request, a variant
+     * an exploration branch. "suggest": a token piece is filed as a suggestion and a variant as a component request, so
+     * the token only needs Issues write. Callers pass changesMode(config), or an explicit choice.
+     */
+    mode?: ChangesMode | undefined;
+}
+/** What writeTokens returns: the pull request it opened, or the suggestion it filed. */
+export type LibraryTokenWrite = {
+    number: number;
+    url: string;
+    branch: string;
+    status?: undefined;
+} | {
+    status: 'suggested';
+    number: number;
+    url: string;
+};
+export interface OpenedLibraryBranch {
+    /** "suggested": the library side is a suggestion (`link.kind` 'suggestion', `link.number` its issue). */
+    status: 'opened' | 'suggested' | 'already-linked' | 'dry-run';
+    plan: LibraryBranchPlan;
+    link: LibraryLink | null;
+    preview: PreviewMerge | null;
+    warnings: string[];
+}
+/** The product branch as the library side names it. */
+export declare function productBranchRef(pull: Pick<Pull, 'number' | 'title' | 'headRef' | 'url' | 'author' | 'body'>, product: ProductConfig): ProductBranchRef;
+/**
+ * Opens the library side of a missing piece and links both ways: the library branch (or request) says "Needed by" the
+ * product branch and carries the `needed-by-product` label; the product branch records the link. A token piece opens a
+ * token change (through `writeTokens`), a variant a library exploration, a new component a request. When the new
+ * library branch already changes something (a token change), the product branch takes its preview.
+ * In suggest mode nothing is a branch: a token piece is a suggestion (through `writeTokens`), a variant and a new
+ * component are requests; recording the link on the product branch is best effort (a warning when refused).
+ */
+export declare function openLibraryBranchOnGitHub(gh: GitHubClient, input: OpenLibraryBranchInput): Promise<OpenedLibraryBranch>;
+export interface LinkedLibraryBranch {
+    link: LibraryLink;
+    piece: MissingPiece | undefined;
+    status: LinkStatus;
+    preview: LibraryPreviewState;
+    /** Requested reviewers of a library pull request, or assignees of a request. */
+    people: string[];
+}
+export interface ProductBranchView {
+    pull: Pull;
+    product: ProductConfig;
+    record: PiecesRecord | undefined;
+    sentence: ReturnType<typeof productBranchSentence>;
+    linked: LinkedLibraryBranch[];
+    /** Pieces with no library branch yet. */
+    open: MissingPiece[];
+}
+/** Where one linked library branch stands, and what its preview means for the product branch. */
+export declare function linkedLibraryBranchOnGitHub(gh: GitHubClient, link: LibraryLink, product: {
+    headSha: string;
+    baseRef: string;
+}, piece?: MissingPiece): Promise<LinkedLibraryBranch>;
+/**
+ * Everything a product branch page shows: the record, the sentence, and each linked library branch with its status,
+ * its reviewers and what its preview means for the product branch. A few reads per linked branch.
+ */
+export declare function productBranchViewOnGitHub(gh: GitHubClient, pr: number, opts: {
+    products: readonly ProductConfig[];
+    viewer?: string | null | undefined;
+    agentName?: string | undefined;
+}): Promise<ProductBranchView>;
+/**
+ * "Switch to the published version": once the library branch shipped, main comes into the product branch (GitHub's
+ * update branch), so the product branch stops carrying the library change and uses the shipped one. Conflicts are
+ * left to bridge_update_from_main or a developer.
+ */
+export declare function switchToPublishedOnGitHub(gh: GitHubClient, pr: number): Promise<{
+    status: 'switched' | 'up-to-date';
+    said: string;
+}>;
+export {};

package/dist/prod-branch.d.ts

@@ -0,0 +1,267 @@
+import type { Exploration } from './explorations';
+import type { ChangesMode } from './config';
+import type { ComponentChangeRequest } from './requests';
+import type { SuggestionStatus } from './suggestions';
+import type { TokenEdit } from './token-edits';
+/** What the library lacks: a token value, a variant of an existing component, or a component. */
+export type PieceKind = 'token' | 'variant' | 'component';
+/** What a variant changes on its component, in designer words. */
+export type PieceAspect = 'tone' | 'shape' | 'size' | 'style';
+export interface PieceValue {
+    /** Audit category: color, radius, spacing... */
+    category: string;
+    /** CSS property, when known: background-color, border-radius. */
+    property?: string | undefined;
+    /** As written: "#c2410c", "10px". */
+    value: string;
+}
+export interface PieceNearest {
+    /** Token path of the closest library value: color.feedback.danger.bg. */
+    token: string;
+    cssVar: string;
+    /** Its value, as the audit resolved it. */
+    value: string;
+    /** How close: high means it looks a lot like it. */
+    level: 'exact' | 'high' | 'medium' | 'low';
+    /** The word people use for it: "danger" for color.feedback.danger.bg, "control" for radius.control. */
+    label: string;
+}
+export interface MissingPiece {
+    /** Stable id inside one product branch: "badge-overdue-tone", "color-c2410c". */
+    id: string;
+    kind: PieceKind;
+    /** Designer title: "Badge: overdue tone", "New color #C2410C", "New component: Timeline". */
+    title: string;
+    /** One plain sentence: what the branch did and what the library has today. */
+    summary: string;
+    /** The name the branch gives it ("overdue"), from a class name, the element's text or the component name. */
+    name: string;
+    /** The library component it extends (variant) or the proposed component name (component). */
+    component?: string | undefined;
+    aspect?: PieceAspect | undefined;
+    values: PieceValue[];
+    nearest?: PieceNearest | undefined;
+    /** Where the branch writes it, first places only. */
+    where: {
+        file: string;
+        line: number;
+    }[];
+    /** Token pieces: the token the library branch would add (one value, every file the closest token lives in). */
+    token?: {
+        path: string;
+        type: string;
+        value: string;
+        files: string[];
+    } | undefined;
+}
+/** Where the library side of a piece lives. A suggestion is an issue holding the exact token change (suggestions.ts). */
+export type LibraryLinkKind = 'token-change' | 'exploration' | 'request' | 'suggestion';
+export interface LibraryLink {
+    /** The piece id. */
+    piece: string;
+    kind: LibraryLinkKind;
+    /** Pull request number (token change, exploration) or issue number (request, suggestion). */
+    number: number;
+    url: string;
+    title: string;
+    /** Head branch of a pull request. */
+    branch?: string | undefined;
+    /** GitHub login of who opened it, and the AI agent behind it ("claude") when one did. */
+    openedBy?: string | undefined;
+    agent?: string | undefined;
+    /** ISO date. */
+    at: string;
+}
+/** What the product branch body keeps: the last check and the library branches opened for its pieces. */
+export interface PiecesRecord {
+    /** ISO date of the last check. */
+    checkedAt: string;
+    /** Head commit the check read. */
+    headSha?: string | undefined;
+    pieces: MissingPiece[];
+    links: LibraryLink[];
+    /** Values and elements the library already has (a token or a component to use instead): fixes, not pieces. */
+    fixes?: number | undefined;
+}
+/** Every library branch opened for a product branch carries this label, so lists can find them without the body. */
+export declare const NEEDED_BY_LABEL = "needed-by-product";
+/** The record in a product branch body, or undefined when the branch was never checked. */
+export declare function parsePiecesRecord(body: string | null | undefined): PiecesRecord | undefined;
+/** The section people read on GitHub, then the hidden record tools read. */
+export declare function piecesSection(r: PiecesRecord): string;
+/** The body with the pieces section replaced, or added at the end. */
+export declare function withPiecesRecord(body: string | null | undefined, r: PiecesRecord): string;
+/**
+ * A new check merged with the previous record: links stay with their piece (same id), and links of pieces the branch
+ * no longer has stay too, so a library branch is never forgotten.
+ */
+export declare function mergePiecesRecord(prev: PiecesRecord | undefined, next: Omit<PiecesRecord, 'links'> & {
+    links?: LibraryLink[] | undefined;
+}): PiecesRecord;
+/** The record with one more link (replacing the piece's earlier one). */
+export declare function withLink(r: PiecesRecord, l: LibraryLink): PiecesRecord;
+export interface NeededBy {
+    /** The product branch (pull request number), its title and branch. */
+    pr: number;
+    title: string;
+    branch: string;
+    url: string;
+    /** Product key and name: "admin", "Admin demo". */
+    product: string;
+    productName: string;
+    /** Who started the product branch (GitHub login). */
+    author?: string | undefined;
+    /** The piece it answers. */
+    piece: string;
+    pieceTitle: string;
+    /** The closest thing the library has today, so a reviewer can suggest it instead: "danger". */
+    nearest?: string | undefined;
+    nearestToken?: string | undefined;
+}
+/** "Needed by" for a library branch body: one line people read, one hidden block tools read. */
+export declare function neededBySection(n: NeededBy): string;
+export declare function parseNeededBy(body: string | null | undefined): NeededBy | undefined;
+/** The body with the "Needed by" section first (replacing an earlier one). */
+export declare function withNeededBy(body: string | null | undefined, n: NeededBy): string;
+export interface ProductBranchRef {
+    pr: number;
+    title: string;
+    branch: string;
+    url: string;
+    productKey: string;
+    productName: string;
+    author?: string | undefined;
+}
+export type LibraryBranchPlan = {
+    kind: 'token-change';
+    title: string;
+    summary: string;
+    edits: TokenEdit[];
+    neededBy: NeededBy;
+} | {
+    kind: 'exploration';
+    title: string;
+    exploration: Exploration;
+    neededBy: NeededBy;
+    brief: string;
+} | {
+    kind: 'request';
+    title: string;
+    request: ComponentChangeRequest;
+    neededBy: NeededBy;
+};
+/**
+ * What a piece opens in the library, honestly labelled by what Bridge can write:
+ * - a token piece: a token change (the new token, a draft for review, the usual gate); in suggest mode the same
+ *   change is filed as a suggestion;
+ * - a variant: a library exploration (a branch and a draft for the component work, with a brief for Claude); in
+ *   suggest mode a component request, since an exploration is a branch;
+ * - a new component: a component request (an issue): it needs design work before code.
+ */
+export declare function libraryBranchPlan(piece: MissingPiece, branch: ProductBranchRef, opts?: {
+    source?: ComponentChangeRequest['source'];
+    requestedBy?: string | undefined;
+    mode?: ChangesMode | undefined;
+}): LibraryBranchPlan;
+export type LinkStatusKey = 'draft' | 'in-review' | 'changes' | 'approved' | 'shipped' | 'closed' | 'exploring' | 'requested' | 'in-progress' | 'done' | 'declined' | 'outdated';
+export interface LinkStatus {
+    key: LinkStatusKey;
+    /** "In review", "Shipped". */
+    label: string;
+    /** Logins asked to review (pull requests), or assignees (requests). */
+    people: string[];
+    /** "In review · @dana reviews". */
+    line: string;
+}
+/** Badge tone of a status: status colours only for status. */
+export declare const LINK_STATUS_TONE: Record<LinkStatusKey, 'neutral' | 'info' | 'warning' | 'success' | 'danger'>;
+/**
+ * Where a library branch stands, from what GitHub says: a pull request (state, draft, labels, requested reviewers,
+ * latest review per person), a request issue (state, reason, assignees, whether a pull request implements it) or a
+ * suggestion (its status, suggestionStatus in suggestions.ts, and who it is assigned to).
+ */
+export declare function linkStatus(x: {
+    kind: 'token-change' | 'exploration';
+    state: string;
+    draft: boolean;
+    labels?: readonly string[] | undefined;
+    requestedReviewers?: readonly string[] | undefined;
+    reviews?: readonly {
+        user?: string | undefined;
+        state: string;
+    }[] | undefined;
+} | {
+    kind: 'request';
+    state: 'open' | 'closed';
+    stateReason?: string | null | undefined;
+    assignees?: readonly string[] | undefined;
+    implemented?: boolean | undefined;
+} | {
+    kind: 'suggestion';
+    status: SuggestionStatus;
+    assignees?: readonly string[] | undefined;
+}): LinkStatus;
+export type LibraryPreviewKey = 'nothing-yet' | 'not-used' | 'preview' | 'outdated' | 'published' | 'switched' | 'declined';
+export interface LibraryPreviewState {
+    key: LibraryPreviewKey;
+    /** One sentence in designer words. */
+    sentence: string;
+    /** The one action that moves it on, when there is one. */
+    action: {
+        kind: 'use-preview' | 'refresh-preview' | 'switch';
+        label: string;
+    } | null;
+}
+/**
+ * What the product branch shows of a library branch, and what to do next:
+ * - while the library branch is open, the product branch carries its commits (Bridge merges the library branch in),
+ *   so the product preview shows the real library change; new library commits make it outdated;
+ * - once the library branch ships, "Switch to the published version" brings main into the product branch: its own
+ *   diff no longer carries the library change, the shipped one is used;
+ * - a request has nothing to preview until someone builds it; a closed library branch says so.
+ *
+ * `missing` is how many library commits the product branch lacks, `total` how many the library branch has on top of
+ * main (null when unknown). `behindMain` is how far the product branch is behind main.
+ */
+export declare function libraryPreviewState(x: {
+    kind: LibraryLinkKind;
+    lifecycle: 'open' | 'merged' | 'closed';
+    /** The library branch changes something beyond its exploration note. */
+    hasChanges: boolean;
+    missing: number | null;
+    total: number | null;
+    behindMain: number | null;
+    nearest?: string | undefined;
+}): LibraryPreviewState;
+/**
+ * The one sentence first on a product branch: "Built with the library. 1 piece was missing, and Claude AI opened a
+ * library branch for it." `who` names who opened the library branches when they are all from the same one.
+ */
+export declare function productBranchSentence(r: PiecesRecord | undefined, opts?: {
+    agentName?: string | undefined;
+    viewer?: string | null | undefined;
+}): {
+    lead: string;
+    strong: string;
+    rest: string;
+};
+/** "Why it exists" on the library review: "Ann needs it for <title> in Admin demo." */
+export declare function whyItExists(n: NeededBy, opts?: {
+    names?: Record<string, string>;
+}): {
+    who: string;
+    title: string;
+    product: string;
+};
+/** The reviewer's question when the closest library value looks a lot like the piece. */
+export declare function nearestQuestion(n: NeededBy, opts?: {
+    names?: Record<string, string>;
+}): string | null;
+/** The review comment of "Suggest <nearest>": request changes with the library value to use instead. */
+export declare function suggestNearestComment(n: NeededBy): string | null;
+/** A piece id from its kind and names: "badge-overdue-tone". */
+export declare function pieceId(parts: (string | undefined)[]): string;
+/** The word people use for a token: the tone in its path, else its last meaningful segment. */
+export declare function tokenLabel(path: string): string;
+/** A new token beside the closest one, named after the piece: color.feedback.danger.bg + "overdue" -> color.feedback.overdue.bg when the closest has a tone, else a sibling. */
+export declare function proposedTokenPath(nearest: string | undefined, name: string, category: string): string;

package/dist/{report-iPSnsjYi.js → report-DOnKUw8G.js}

@@ -1,4 +1,4 @@
-import { h as hexToRgba, c as comboKey } from "./layered-BnbmToGs.js";
+import { bn as hexToRgba, aW as comboKey } from "./prod-branch-BdMPKffE.js";
 import ts from "typescript";
 const AUDIT_SCHEMA_VERSION = 1;
 const FINDING_CATEGORIES = ["color", "spacing", "size", "radius", "border-width", "shadow", "duration", "easing", "z-index", "font-family", "font-size", "font-weight", "line-height"];
@@ -1880,31 +1880,31 @@ export {
   tailwindColor as X,
   tailwindFindings as Y,
   toOklab as Z,
-  AUDIT_IGNORE_DIRS as a,
-  AUDIT_SCHEMA_VERSION as b,
-  DesignSystemIndex as c,
-  LOOKALIKE_CLASSES as d,
-  applyAllowlist as e,
-  applyIgnoreComments as f,
-  auditCssText as g,
-  auditFile as h,
-  auditMarkdown as i,
-  blankComments as j,
-  buildAuditReport as k,
-  classifyModule as l,
-  classifyTag as m,
-  compareWithBaseline as n,
-  cssPropertyOf as o,
-  deltaE as p,
-  domRendererComponent as q,
-  dsEquivalent as r,
-  historyPoint as s,
-  ignoreDirectives as t,
-  importsOf as u,
-  isAuditable as v,
+  auditFile as a,
+  AUDIT_IGNORE_DIRS as b,
+  AUDIT_SCHEMA_VERSION as c,
+  DesignSystemIndex as d,
+  LOOKALIKE_CLASSES as e,
+  applyAllowlist as f,
+  applyIgnoreComments as g,
+  auditCssText as h,
+  isAuditable as i,
+  auditMarkdown as j,
+  blankComments as k,
+  buildAuditReport as l,
+  classifyModule as m,
+  classifyTag as n,
+  compareWithBaseline as o,
+  cssPropertyOf as p,
+  deltaE as q,
+  domRendererComponent as r,
+  dsEquivalent as s,
+  historyPoint as t,
+  ignoreDirectives as u,
+  importsOf as v,
   isColorLiteral as w,
   isNonVisual as x,
   isRouterLink as y,
   isSafeFix as z
 };
-//# sourceMappingURL=report-iPSnsjYi.js.map
+//# sourceMappingURL=report-DOnKUw8G.js.map