@bridge-ds/core 0.3.0 → 0.4.0

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.3.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",