@bridge-ds/core 0.7.0 → 0.9.0

package/dist/prod-branch.d.ts

@@ -0,0 +1,257 @@
+import type { Exploration } from './explorations';
+import type { ComponentChangeRequest } from './requests';
+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. */
+export type LibraryLinkKind = 'token-change' | 'exploration' | 'request';
+export interface LibraryLink {
+    /** The piece id. */
+    piece: string;
+    kind: LibraryLinkKind;
+    /** Pull request number (token change, exploration) or issue number (request). */
+    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);
+ * - a variant: a library exploration (a branch and a draft for the component work, with a brief for Claude);
+ * - 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;
+}): LibraryBranchPlan;
+export type LinkStatusKey = 'draft' | 'in-review' | 'changes' | 'approved' | 'shipped' | 'closed' | 'exploring' | 'requested' | 'in-progress' | 'done' | 'declined';
+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) or a request issue (state, reason, assignees, whether a pull request implements it).
+ */
+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;
+}): 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/products.d.ts

@@ -19,6 +19,15 @@ export declare const DEFAULT_PRODUCTS: ProductConfig[];
 /** Pull request labels that pin a branch to a product ("product: admin"). */
 export declare const PRODUCT_LABEL_PREFIX = "product: ";
 export declare const productLabel: (key: string) => string;
+/**
+ * Labels and a body line for new work started for a product (a branch, an exploration, a request): the
+ * `product: <key>` label and "**Product:** <name>". The default product adds nothing, since productOfBranch lands
+ * an unlabeled branch there. Studio, the CLI and the MCP server all write these.
+ */
+export declare function productMarks(products: readonly ProductConfig[], p: ProductConfig): {
+    labels: string[];
+    line: string;
+};
 /** The configured products, or DEFAULT_PRODUCTS when the config lists none. */
 export declare function productsOf(config: {
     products?: ProductConfig[] | undefined;

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

@@ -1,4 +1,4 @@
-import { h as hexToRgba, c as comboKey } from "./layered-BnbmToGs.js";
+import { bc as hexToRgba, aN as comboKey } from "./pr-composer-D2SZm7cg.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-DY_peRy4.js.map