@bridge-ds/core 0.8.0 → 0.10.0

package/dist/token-proposal.d.ts

@@ -0,0 +1,123 @@
+import type { BridgeConfig } from './config';
+import type { GitHubClient } from './github-client';
+import type { NeededBy } from './prod-branch';
+import type { RequestSource } from './requests';
+import { type SuggestionPayloadV1 } from './suggestions';
+import { LayeredTokenSet, type LayerIssue } from './layered';
+import { type ChangeTier, type ContrastDelta, type ImpactEntry, type LayeredChange } from './layered-review';
+import { type TokenEdit } from './token-edits';
+import type { ContrastPair } from './wcag';
+export interface TokenProposalPlan {
+    title: string;
+    summary: string;
+    /** The token edits the plan applied: what a suggestion stores and re-applies on the current tokens. */
+    edits: TokenEdit[];
+    before: LayeredTokenSet;
+    after: LayeredTokenSet;
+    changes: LayeredChange[];
+    tier: ChangeTier;
+    contrast: ContrastDelta[];
+    newFailures: ContrastDelta[];
+    newErrors: LayerIssue[];
+    impact: {
+        total: number;
+        entries: ImpactEntry[];
+    };
+    notes: string[];
+    /** Token files edited, as repo paths. */
+    touched: string[];
+    /** Every file the commit writes: the token files and the changeset. */
+    files: {
+        path: string;
+        content: string | null;
+    }[];
+    body: string;
+    /** Branch slug from the title. */
+    slug: string;
+    /** Why it cannot be opened (new validation errors, failing contrast pairs), or null. */
+    blocked: string | null;
+}
+/**
+ * What a token change would do, without writing: the token diff, validation and contrast against `before`, the tier,
+ * the body and the files. `blocked` says why it must not be opened. Null when the edits change nothing.
+ */
+export declare function planTokenProposal(input: {
+    before: LayeredTokenSet;
+    pairs: ContrastPair[];
+    edits: TokenEdit[];
+    title: string;
+    summary?: string | undefined;
+    config: BridgeConfig;
+    /** "Bridge MCP", "Bridge Studio". */
+    tool?: string | undefined;
+    /** More body paragraphs, after the generated body (the product line, "Needed by"). */
+    bodyExtra?: string[] | undefined;
+}): TokenProposalPlan | null;
+export interface OpenedTokenProposal {
+    branch: string;
+    commit: string;
+    pr: number;
+    url: string;
+    labels: string[];
+    draft: boolean;
+}
+/**
+ * Opens a planned token change on GitHub: a new branch from `base` (the agent prefix, the Jira key, -2, -3 when the name
+ * is taken), one commit, a pull request (a draft from tier 2, until design review) and its labels. Refuses a blocked plan.
+ */
+export declare function writeTokenProposalOnGitHub(gh: GitHubClient, plan: TokenProposalPlan, opts: {
+    base: string;
+    branchPrefix: string;
+    jira?: string | null | undefined;
+    /** Labels before the tier ones (governance.labels), and after them (the product label). */
+    labels?: string[] | undefined;
+    labelsAfter?: string[] | undefined;
+    /** Who proposes it, in the commit message: "Bridge MCP (source: mcp)". */
+    tool?: string | undefined;
+}): Promise<OpenedTokenProposal>;
+export interface SuggestedTokenProposal {
+    status: 'suggested';
+    /** The suggestion issue. */
+    number: number;
+    url: string;
+    /** sha256 of the payload: what approvals bind to. */
+    sha: string;
+    labels: string[];
+    /** Sentences about parts that did not go through (labels refused). The suggestion itself holds. */
+    warnings: string[];
+}
+/** The suggestion payload (bridge.suggestion/1) of a planned token change, computed on `base`. Pure. */
+export declare function tokenSuggestionPayload(plan: TokenProposalPlan, ctx: {
+    base: {
+        ref: string;
+        sha: string;
+    };
+    source: RequestSource;
+    suggestedBy?: string | undefined;
+    createdAt?: string | undefined;
+    links?: SuggestionPayloadV1['links'];
+    previews?: SuggestionPayloadV1['previews'];
+}): SuggestionPayloadV1;
+/**
+ * Files a planned token change as a suggestion (suggest mode): one issue with the readable change, the checks and the
+ * exact edits, labelled like the pull request would be (tier, tokens, breaking), plus the suggestion labels. Needs
+ * Issues write only: no branch, no commit, no pull request. Refuses a blocked plan, like writeTokenProposalOnGitHub.
+ */
+export declare function suggestTokenProposalOnGitHub(gh: GitHubClient, plan: TokenProposalPlan, opts: {
+    /** Default branch the plan was computed on. Its head commit is recorded as the suggestion's base. */
+    base: string;
+    source: RequestSource;
+    /** GitHub login of who suggests it. */
+    suggestedBy?: string | undefined;
+    /** Labels before the tier ones (governance.labels), and after them (the product label). */
+    labels?: string[] | undefined;
+    labelsAfter?: string[] | undefined;
+    /** The product branch that needs it (a missing piece). */
+    neededBy?: NeededBy | undefined;
+    /** The Figma origin, a suggestion it replaces. */
+    links?: SuggestionPayloadV1['links'];
+    previews?: SuggestionPayloadV1['previews'];
+    assignees?: string[] | undefined;
+    /** Commit sha of `base`, when the caller already read it (saves a call). */
+    baseSha?: string | undefined;
+}): Promise<SuggestedTokenProposal>;

package/package.json

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