@bridge-ds/core 0.18.0 → 0.19.0

package/dist/gap-case.d.ts

@@ -0,0 +1,144 @@
+import { type ComponentSpec, type SpecField, type SpecPart, type SpecValue, type SpecVariant } from './component-spec';
+import type { FidelityComponentResult, Size } from './fidelity';
+import { type MeasuredBox, type MeasuredSpec, type MeasuredSpecsFile, type MeasuredSpecsStory, type MeasuredState } from './measured-spec';
+export declare const GAP_CASE_VERSION = 1;
+/** How a story reaches a variant: at rest, a forced pseudo state, or disabled (an arg). */
+export type GapState = 'rest' | MeasuredState | 'disabled';
+/**
+ * What a difference is about. A Figma field (fill, paddingTop, cornerRadius, height...), or: `presence` (a part one side
+ * draws and the other does not), `sizing` (fixed in code, hugging in Figma), `direction` (auto layout direction).
+ */
+export type GapProperty = SpecField | 'presence' | 'sizing' | 'direction';
+/** One concrete difference. `expected` is the code (the measure), `actual` is Figma (what was drawn). */
+export interface GapDifference {
+    /** Plain words: "Height 72 in Figma vs 84 in code: 12 px missing below the label wrapper". */
+    text: string;
+    /** Part id, as the measure and the built set name it ("root", "cds--toggle-switch"). */
+    part: string;
+    /** The part in words ("toggle switch"). */
+    partName: string;
+    property: GapProperty;
+    /** Code: token path, px number, null (no paint), `present`, `fixed`, `HORIZONTAL`... */
+    expected: SpecValue | boolean;
+    /** Figma: the same kinds, `missing`, `hidden`, `hug`... */
+    actual: SpecValue | boolean;
+    /** Numbers: actual minus expected, px (negative: Figma is smaller). */
+    delta?: number | undefined;
+}
+export interface GapStoryRef {
+    /** Storybook story id. */
+    id: string;
+    name?: string | undefined;
+    /** Story URL the measure opened (args in it). */
+    url?: string | undefined;
+    /** The props it rendered with (args over the component defaults), and the args Bridge passed to reach the variant. */
+    props: Record<string, string | number | boolean>;
+    overrides?: Record<string, string | number | boolean> | undefined;
+    state: GapState;
+}
+export interface GapVariant {
+    /** Figma variant key (variantKeyOf: "Size=md, State=Default"). */
+    key: string;
+    /** Figma props of the variant. */
+    props: Record<string, string>;
+    /** The referee's verdict for this variant: the plugin's Check fidelity (`unchecked` without one). */
+    verdict: 'differs' | 'unchecked';
+    /** Different pixels in percent, and both sizes, when the shot was compared. */
+    percent?: number | undefined;
+    size?: {
+        figma: Size;
+        code: Size;
+    } | undefined;
+    story?: GapStoryRef | undefined;
+    /** The story's screenshot, relative to measured-specs.json (the referee image). */
+    shot?: string | undefined;
+    /** What Figma drew for this variant: a node id or an exported PNG, when the plugin passes one. */
+    figmaRender?: string | undefined;
+    differences: GapDifference[];
+    /** Why the list is empty when the shots differ: no story, or the measure agrees and only the images tell. */
+    unexplained?: string | undefined;
+}
+export interface GapCase {
+    version: typeof GAP_CASE_VERSION;
+    component: string;
+    storybook: string;
+    /** `shots`: the variants come from the fidelity check. `values`: no check was passed, variants with differences. */
+    referee: 'shots' | 'values';
+    /** Variants compared, and how many differ. */
+    checked: number;
+    differing: number;
+    /** One sentence for a designer. */
+    summary: string;
+    /** Lines for a developer (or Claude): story, args, state, shot and every delta per variant. */
+    detail: string;
+    variants: GapVariant[];
+    /** Fixes from figma-fixes.json already applied to this component (the patched measure says so). */
+    fixes?: string[] | undefined;
+}
+/** What the plugin reads back from one drawn variant, laid over the spec it drew from. All optional. */
+export interface GapBuiltVariant {
+    /** Field values the layers hold (part id -> field -> value), when they differ from the spec's. */
+    values?: SpecVariant['values'] | undefined;
+    /** Parts hidden in this variant. */
+    hidden?: string[] | undefined;
+    /** Part id -> its box relative to the variant's top-left, px: lets the gap say where space is missing. */
+    boxes?: Record<string, MeasuredBox> | undefined;
+}
+export interface GapCaseInput {
+    /** Set name ("Toggle"): the last segment of the stories' title. */
+    component: string;
+    measured: MeasuredSpecsFile;
+    /** What the pull drew the set from (specsFromMeasure's spec, or the overlaid static spec). */
+    spec?: ComponentSpec | undefined;
+    /** The plugin's Check fidelity result for this set: the referee. */
+    fidelity?: FidelityComponentResult | undefined;
+    /** Variant key -> what the layers read back. */
+    built?: Record<string, GapBuiltVariant> | undefined;
+    /** Variant key -> the story shot the set was compared with (MeasuredShots[set]). */
+    shots?: Record<string, {
+        file: string;
+    }> | undefined;
+    /** Variant key -> a reference to what Figma drew (node id, PNG path). */
+    figmaRenders?: Record<string, string> | undefined;
+    /** Token path -> its value in the measured page. Default: the measure's resolved values and token harvest. */
+    resolve?: ((tokenPath: string) => string | number | undefined) | undefined;
+}
+/** The stories of a set: the last title segment, case and punctuation ignored. */
+export declare function storiesOfComponent(file: Pick<MeasuredSpecsFile, 'stories'>, component: string): MeasuredSpecsStory[];
+/** A story's state: its forced pseudo state, else disabled when the arg says so, else at rest. */
+export declare function storyState(s: Pick<MeasuredSpecsStory, 'state' | 'props' | 'overrides'>): GapState;
+/**
+ * The story a Figma variant was drawn from: the one whose shot it was compared with, else the first (single instance
+ * before galleries) whose props, overrides and state give the variant's axis values.
+ */
+export declare function storyForVariant(spec: Pick<ComponentSpec, 'axes'>, props: Record<string, string>, stories: MeasuredSpecsStory[], shot?: {
+    file: string;
+}): MeasuredSpecsStory | undefined;
+/** A part in words: the measure's ids are class names ("cds--toggle__switch" -> "toggle switch"). */
+export declare function partWords(part: Pick<SpecPart, 'id' | 'name'> | undefined, id?: string): string;
+/** Token path -> value, from the measure: components[].resolved, then the token harvest (by CSS name). */
+export declare function measuredResolver(file: Pick<MeasuredSpecsFile, 'components' | 'tokens'>): (path: string) => string | number | undefined;
+export interface VariantGapInput {
+    /** The parts the set was drawn with, and this variant's values and hidden parts. */
+    parts: SpecPart[];
+    variant: Pick<SpecVariant, 'values' | 'hidden' | 'layout'>;
+    properties?: ComponentSpec['properties'] | undefined;
+    built?: GapBuiltVariant | undefined;
+    measured: MeasuredSpec;
+    /** The fidelity check's sizes (CSS px), when the shot was compared. */
+    size?: {
+        figma: Size;
+        code: Size;
+    } | undefined;
+    resolve?: ((tokenPath: string) => string | number | undefined) | undefined;
+}
+/**
+ * The differences between what Figma drew for one variant and what the code renders (its measured story): the size and
+ * where it comes from, parts one side lacks, fixed sizes Figma hugs, auto layout direction, then field values.
+ */
+export declare function variantDifferences(input: VariantGapInput): GapDifference[];
+/**
+ * The gap case of one component: the variants the referee says differ (the fidelity check; without one, every variant
+ * with a difference), each with its story, args, state, shot, Figma render and the differences in words and deltas.
+ */
+export declare function buildGapCase(input: GapCaseInput): GapCase;

package/dist/github-client.d.ts

@@ -15,6 +15,8 @@ export interface GitHubErrorInfo {
     auth?: GitHubAuthState | undefined;
     /** The permission the call needed, when GitHub or the endpoint tells (only with auth "missing-permission"). */
     permission?: GitHubPermission | undefined;
+    /** For a rate limit (status 429): when the limit resets, when GitHub or Bridge said. */
+    resetsAt?: Date | undefined;
 }
 export declare class GitHubError extends Error {
     readonly status: number;
@@ -23,6 +25,8 @@ export declare class GitHubError extends Error {
     readonly auth: GitHubAuthState | undefined;
     /** With auth "missing-permission": the permission the call needed, when known. */
     readonly permission: GitHubPermission | undefined;
+    /** For a rate limit (status 429): when the limit resets, when known. */
+    readonly resetsAt: Date | undefined;
     constructor(status: number, message: string, detail?: string | undefined, info?: GitHubErrorInfo);
 }
 /** True when `err` says GitHub refused the token itself (revoked, regenerated or expired). */
@@ -96,6 +100,8 @@ export interface Review {
     state: string;
     body: string;
     submittedAt?: string | undefined;
+    /** The commit the review was given on (GitHub `commit_id`). */
+    commitId?: string | undefined;
 }
 export interface PullRequestSummary {
     number: number;
@@ -112,6 +118,11 @@ export interface PullRequestSummary {
     updatedAt: string;
     /** Description, when the list endpoint returns it (component change requests read "Closes #n" from it). */
     body?: string | undefined;
+    /** ISO dates, when GitHub returns them (build requests: in progress since, shipped on). */
+    createdAt?: string | undefined;
+    mergedAt?: string | undefined;
+    /** Who is assigned (logins), when any. */
+    assignees?: string[] | undefined;
 }
 export interface ClientOptions {
     /** API base, for GitHub Enterprise or tests. */
@@ -340,8 +351,23 @@ export declare class GitHubClient {
      */
     private paged;
     getRepo(): Promise<RepoInfo>;
+    /**
+     * What the token may write here, found without writing anything: each probe is invalid on purpose (a zero sha, a
+     * missing head branch, an empty title), so GitHub answers 422 when the token has the permission and 403 or 404 when
+     * it does not. repo.permissions.push says what the user may do, not what a fine-grained token may do.
+     */
+    writeAccess(base: string): Promise<{
+        contents: boolean;
+        pullRequests: boolean;
+        issues: boolean;
+    }>;
     /** Commit sha a branch points to, or undefined when the branch does not exist. */
     getBranchSha(branch: string): Promise<string | undefined>;
+    /**
+     * Whether a branch exists, through the matching-refs list: it answers 200 with an empty list when the branch is
+     * missing, so asking never leaves a 404 in the browser console (an optional branch like bridge-data).
+     */
+    hasBranch(branch: string): Promise<boolean>;
     getCommitTree(commitSha: string): Promise<string>;
     getTree(treeSha: string, recursive?: boolean): Promise<{
         entries: TreeEntry[];
@@ -609,6 +635,7 @@ export declare class GitHubClient {
         body: string;
         mergeable: boolean | null;
         requestedReviewers: string[];
+        autoMerge: boolean;
     }>;
     listPullRequestFiles(n: number): Promise<PullRequestFile[]>;
     updatePullRequest(n: number, patch: {
@@ -782,4 +809,8 @@ export interface IssueSummary {
     author: string;
     createdAt: string;
     updatedAt: string;
+    /** Who is assigned (logins), when any (build requests: "Ana is on it"). */
+    assignees?: string[] | undefined;
+    /** ISO date it was closed, when closed. */
+    closedAt?: string | undefined;
 }

package/dist/id-map.d.ts

@@ -17,6 +17,16 @@ export interface ReconcileResult {
 export declare function levenshtein(a: string, b: string): number;
 export declare function pathSimilarity(a: string, b: string): number;
 export declare const SIMILARITY_THRESHOLD = 0.5;
+/**
+ * Tokens the code renamed between two commits: removed and added between `base` and `head` with the same type, tier
+ * and values and a similar path. One pair per token; a token that matches more than one counterpart equally is left
+ * as a removal and an addition (no guess). Lets a pull rename the Figma variable instead of orphaning it and adding a
+ * new one, so everything bound to it keeps its binding.
+ */
+export declare function remoteRenames(base: Map<string, LogicalToken>, head: Map<string, LogicalToken>): {
+    from: LogicalToken;
+    to: LogicalToken;
+}[];
 /**
  * Align Figma token ids with Git ids. `git` is every token known on the Git side (base and head).
  * Heuristic candidates are restricted to Git tokens that no Figma variable claims.

package/dist/index.d.ts

@@ -43,8 +43,16 @@ export * from './explorations';
 export * from './explorations-github';
 export * from './requests-github';
 export * from './component-spec';
+export * from './measured-spec';
+export * from './measured-tokens';
+export * from './measure-status';
 export * from './fidelity';
 export * from './fidelity-references';
+export * from './gap-case';
+export * from './figma-fixes';
+export * from './measured-only';
+export * from './css-color';
+export * from './figma-fix-loop';
 export * from './review-gate';
 export * from './library-update';
 export * from './branch-actions';
@@ -72,5 +80,10 @@ export * from './component-scan';
 export * from './repo-model';
 export * from './repo-source-github';
 export * from './repo-access';
+export * from './changelog-model';
+export * from './motion-docs';
 export * from './snapshot';
+export * from './requester';
 export * from './activity';
+export * from './build-requests';
+export * from './build-requests-github';