@bridge-ds/mcp 0.0.0-stage → 0.3.0

package/dist/ops.d.ts

@@ -0,0 +1,739 @@
+import { type ScaffoldInput } from './components.js';
+import type { BridgeContext } from './context.js';
+import { type BridgeConfig, type GitHubClient } from '@bridge-ds/core';
+import { type Combo, type PairInput, type TokenEdit, type TokenSet } from './core-adapter.js';
+/** Accepts `color.text.muted`, `--color-text-muted` or `var(--color-text-muted)`. */
+export declare function normalizeTokenPath(set: TokenSet, input: string): string;
+export declare function getConfig(ctx: BridgeContext): Promise<{
+    source: string;
+    configOrigin: string;
+    write: string;
+    repo: string | null;
+    tokenFiles: number;
+    tokens: number;
+    tokensPerTier: {
+        [k: string]: number;
+    };
+    modes: Record<string, import("@bridge-ds/core").ModeAxis>;
+    modeCombinations: number;
+    config: BridgeConfig;
+}>;
+export declare function listTokens(ctx: BridgeContext, a: {
+    tier?: string;
+    type?: string;
+    prefix?: string;
+    mode?: Partial<Combo>;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    next?: string | undefined;
+    mode: Combo;
+    total: number;
+    offset: number;
+    returned: number;
+    tokens: {
+        alias?: string | undefined;
+        path: string;
+        type: string | undefined;
+        tier: string | undefined;
+        value: string;
+    }[];
+}>;
+export declare function getToken(ctx: BridgeContext, a: {
+    path: string;
+}): Promise<{
+    definedIn: {
+        file: string;
+        tier: string | undefined;
+        value: unknown;
+    }[];
+    values: {
+        modes: string[];
+        value: string;
+        chain: string[];
+    }[];
+    referencedBy: string[];
+    usedIn: {
+        component: string;
+        file: string;
+        via?: string;
+    }[];
+    description?: string | undefined;
+    path: string;
+    cssVar: string;
+    type: string | undefined;
+    tier: string | undefined;
+}>;
+export declare function searchTokens(ctx: BridgeContext, a: {
+    query: string;
+    type?: string;
+    limit?: number;
+}): Promise<{
+    query: string;
+    mode: Combo;
+    total: number;
+    results: {
+        description?: string | undefined;
+        path: string;
+        score: number;
+        type: string | undefined;
+        tier: string | undefined;
+        value: string;
+    }[];
+}>;
+export declare function checkContrast(ctx: BridgeContext, a: {
+    edits?: TokenEdit[];
+    pairs?: PairInput[];
+    mode?: Partial<Combo>;
+    includePassing?: boolean;
+}): Promise<{
+    results?: import("@bridge-ds/core").LayeredContrastResult[] | undefined;
+    source: string | undefined;
+    checks: number;
+    failing: number;
+    failures: import("@bridge-ds/core").LayeredContrastResult[];
+    tightest: {
+        pair: string;
+        modes: string;
+        ratio: number | null;
+        min: number;
+    }[];
+} | {
+    pairs: number;
+    message: string;
+} | {
+    edits: number;
+    notes: string[];
+    changed: import("@bridge-ds/core").ContrastDelta[];
+    newFailures: import("@bridge-ds/core").ContrastDelta[];
+    results?: import("@bridge-ds/core").LayeredContrastResult[] | undefined;
+    source: string | undefined;
+    checks: number;
+    failing: number;
+    failures: import("@bridge-ds/core").LayeredContrastResult[];
+    tightest: {
+        pair: string;
+        modes: string;
+        ratio: number | null;
+        min: number;
+    }[];
+    pairs?: undefined;
+    message?: undefined;
+}>;
+export declare function validateTokens(ctx: BridgeContext, a: {
+    edits?: TokenEdit[];
+    includeWarnings?: boolean;
+}): Promise<{
+    valid: boolean;
+    files: number;
+    tokens: number;
+    modeCombinations: number;
+    errors: import("@bridge-ds/core").LayerIssue[];
+    warningCount: number;
+} | {
+    notes: string[];
+    newErrors: import("@bridge-ds/core").LayerIssue[];
+    warnings: import("@bridge-ds/core").LayerIssue[];
+    valid: boolean;
+    files: number;
+    tokens: number;
+    modeCombinations: number;
+    errors: import("@bridge-ds/core").LayerIssue[];
+    warningCount: number;
+} | {
+    notes: string[];
+    newErrors: import("@bridge-ds/core").LayerIssue[];
+    warningSample: import("@bridge-ds/core").LayerIssue[];
+    valid: boolean;
+    files: number;
+    tokens: number;
+    modeCombinations: number;
+    errors: import("@bridge-ds/core").LayerIssue[];
+    warningCount: number;
+} | {
+    notes: string[];
+    newErrors: import("@bridge-ds/core").LayerIssue[];
+    valid: boolean;
+    files: number;
+    tokens: number;
+    modeCombinations: number;
+    errors: import("@bridge-ds/core").LayerIssue[];
+    warningCount: number;
+}>;
+export declare function listComponentsOp(ctx: BridgeContext, a: {
+    withSummaries?: boolean;
+    family?: string;
+}): Promise<{
+    components: never[];
+    message: string;
+    dir?: undefined;
+    total?: undefined;
+} | {
+    dir: string;
+    total: number;
+    components: import("./components.js").ComponentSummary[];
+    message?: undefined;
+}>;
+export declare function getComponentOp(ctx: BridgeContext, a: {
+    name: string;
+    include?: string[];
+}): Promise<{
+    tokens: {
+        notTokens?: string[] | undefined;
+        used: string[];
+    };
+    stories: string[];
+    extends?: string | undefined;
+    props: import("./components.js").PropInfo[];
+    docs?: Record<string, unknown> | undefined;
+    name: string;
+    family: string | undefined;
+    files: string[];
+}>;
+/**
+ * bridge_draft_docs: the deterministic pre-fill of a component's docs.json (props table, tokens, anatomy from the
+ * CSS module classes, contrast notes, changelog line, existing prose kept) and a prompt for the user's own Claude
+ * to write the prose that code cannot tell. Nothing is written.
+ */
+export declare function draftDocsOp(ctx: BridgeContext, a: {
+    name: string;
+    branch?: string | undefined;
+}): Promise<{
+    branch?: string | undefined;
+    rules?: string[] | undefined;
+    component: string;
+    path: string;
+    exists: boolean;
+    prefill: import("@bridge-ds/core").DocsPrefill;
+    prompt: string;
+    instruction: string;
+}>;
+export declare function getDesignLanguage(ctx: BridgeContext, a: {
+    section?: string;
+}): Promise<{
+    file: string | undefined;
+    sections: {
+        level: number;
+        title: string;
+        slug: string;
+    }[];
+    hint: string;
+    error?: undefined;
+} | {
+    file: string | undefined;
+    error: string;
+    sections: {
+        level: number;
+        title: string;
+        slug: string;
+    }[];
+    hint?: undefined;
+} | {
+    otherMatches?: string[] | undefined;
+    file: string | undefined;
+    text: string;
+    sections?: undefined;
+    hint?: undefined;
+    error?: undefined;
+}>;
+export declare function getGuidelines(ctx: BridgeContext, a: {
+    section?: string;
+}): Promise<{
+    file: string | undefined;
+    text: string;
+    error?: undefined;
+    sections?: undefined;
+} | {
+    file: string | undefined;
+    error: string;
+    sections: {
+        level: number;
+        title: string;
+        slug: string;
+    }[];
+    text?: undefined;
+} | {
+    bridgeEnforces: string[];
+    sections: {
+        level: number;
+        title: string;
+        slug: string;
+    }[];
+    riskTiers?: string | undefined;
+    file: string | undefined;
+    always: string[];
+    askBefore: string[];
+    never: string[];
+    tokenConventions: string[];
+    text?: undefined;
+    error?: undefined;
+}>;
+export declare function proposeTokenChange(ctx: BridgeContext, a: {
+    edits: TokenEdit[];
+    title: string;
+    summary?: string;
+    dryRun?: boolean;
+    branch?: string | undefined;
+}): Promise<{
+    status: string;
+    message: string;
+} | {
+    hint: string;
+    title: string;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    changes: {
+        fields?: ("value" | "description" | "type" | "extensions")[] | undefined;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+        from?: string | undefined;
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+    }[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+    };
+    impact: {
+        total: number;
+        sample: import("@bridge-ds/core").ImpactEntry[];
+    };
+    notes: string[];
+    status: string;
+    why: string;
+    newErrors: import("@bridge-ds/core").LayerIssue[];
+    message?: undefined;
+} | {
+    fileContents: {
+        path: string;
+        content: string | null;
+    }[];
+    branch: string;
+    files: string[];
+    prBody: string;
+    title: string;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    changes: {
+        fields?: ("value" | "description" | "type" | "extensions")[] | undefined;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+        from?: string | undefined;
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+    }[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+    };
+    impact: {
+        total: number;
+        sample: import("@bridge-ds/core").ImpactEntry[];
+    };
+    notes: string[];
+    status: string;
+    message?: undefined;
+} | {
+    status: "preview";
+    message: string;
+    branch: string;
+    next?: undefined;
+    exploration: boolean;
+    files: string[];
+    prBody: string;
+    title: string;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    changes: {
+        fields?: ("value" | "description" | "type" | "extensions")[] | undefined;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+        from?: string | undefined;
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+    }[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+    };
+    impact: {
+        total: number;
+        sample: import("@bridge-ds/core").ImpactEntry[];
+    };
+    notes: string[];
+} | {
+    next: string;
+    pr?: number | undefined;
+    url?: string | undefined;
+    status: "committed";
+    branch: string;
+    commit: string;
+    message?: undefined;
+    exploration: boolean;
+    files: string[];
+    prBody: string;
+    title: string;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    changes: {
+        fields?: ("value" | "description" | "type" | "extensions")[] | undefined;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+        from?: string | undefined;
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+    }[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+    };
+    impact: {
+        total: number;
+        sample: import("@bridge-ds/core").ImpactEntry[];
+    };
+    notes: string[];
+} | {
+    status: "written";
+    branch: string;
+    next: string;
+    message?: undefined;
+    exploration: boolean;
+    files: string[];
+    prBody: string;
+    title: string;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    changes: {
+        fields?: ("value" | "description" | "type" | "extensions")[] | undefined;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+        from?: string | undefined;
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+    }[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+    };
+    impact: {
+        total: number;
+        sample: import("@bridge-ds/core").ImpactEntry[];
+    };
+    notes: string[];
+} | {
+    fileContents: {
+        path: string;
+        content: string | null;
+    }[];
+    branch: string;
+    files: string[];
+    prBody: string;
+    title: string;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    changes: {
+        fields?: ("value" | "description" | "type" | "extensions")[] | undefined;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+        from?: string | undefined;
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+    }[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+    };
+    impact: {
+        total: number;
+        sample: import("@bridge-ds/core").ImpactEntry[];
+    };
+    notes: string[];
+    status: string;
+    message: string;
+} | {
+    branch: string;
+    base: string;
+    commit: string;
+    diff: string;
+    next: string;
+    files: string[];
+    prBody: string;
+    title: string;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    changes: {
+        fields?: ("value" | "description" | "type" | "extensions")[] | undefined;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+        from?: string | undefined;
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+    }[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+    };
+    impact: {
+        total: number;
+        sample: import("@bridge-ds/core").ImpactEntry[];
+    };
+    notes: string[];
+    status: string;
+    message?: undefined;
+} | {
+    branch: string;
+    commit: string;
+    pr: number;
+    url: string;
+    labels: string[];
+    draft: boolean;
+    files: string[];
+    prBody: string;
+    title: string;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    changes: {
+        fields?: ("value" | "description" | "type" | "extensions")[] | undefined;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+        from?: string | undefined;
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+    }[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+    };
+    impact: {
+        total: number;
+        sample: import("@bridge-ds/core").ImpactEntry[];
+    };
+    notes: string[];
+    status: string;
+    message?: undefined;
+}>;
+export declare function listReviews(ctx: BridgeContext, a: {
+    state?: 'open' | 'closed' | 'all';
+    onlyBridge?: boolean;
+}): Promise<Record<string, unknown>>;
+export declare function getReview(ctx: BridgeContext, a: {
+    pr?: number;
+    branch?: string;
+}): Promise<{
+    tokenChanges: number;
+    diffTable: string;
+    contrastTable: string;
+    contrastNewFailures: number;
+    validation: {
+        errors: number;
+        newErrors: import("@bridge-ds/core").LayerIssue[];
+    };
+    impact: {
+        total: number;
+        entries: import("@bridge-ds/core").ImpactEntry[];
+    };
+    tierWarning?: string | undefined;
+    changedFiles: string[];
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+}>;
+/**
+ * Who holds each role for a review, teams included: governance.owners through governance.rights, each GitHub team
+ * read from GitHub and named with its size ("@acme/design (4 people)"). An approval counts for a role when the
+ * reviewer is listed or in a listed team. A team that cannot be read is named with the reason, never dropped.
+ */
+export declare function reviewRoles(gh: GitHubClient, config: BridgeConfig, approvers: string[]): Promise<{
+    unreadableTeams?: string[] | undefined;
+    design: {
+        owners: string[];
+        approvedBy: string[];
+    };
+    tech: {
+        owners: string[];
+        approvedBy: string[];
+    };
+    ship: string;
+}>;
+export declare function reviewPr(ctx: BridgeContext, a: {
+    pr: number;
+    event: 'comment' | 'approve' | 'request_changes';
+    body: string;
+}): Promise<{
+    pr: number;
+    event: "COMMENT" | "APPROVE" | "REQUEST_CHANGES";
+    id: number;
+    state: string;
+    note: string | undefined;
+}>;
+export declare function scaffoldComponentOp(ctx: BridgeContext, a: ScaffoldInput & {
+    write?: boolean;
+}): Promise<{
+    written: boolean;
+    tier: number;
+    files: string[] | {
+        path: string;
+        content: string;
+    }[];
+    nextSteps: string[];
+}>;
+export declare function auditUi(ctx: BridgeContext, code: string): Promise<import("./audit.js").Finding[]>;
+/**
+ * Visual impact of a change: screenshots of the stories and app screens it touches at both refs, pixel-diffed.
+ * Local repos only (it builds Storybook and the app). `plan` returns the selection without building.
+ */
+export declare function visualImpact(ctx: BridgeContext, a: {
+    base?: string;
+    head?: string;
+    out?: string;
+    only?: ('stories' | 'app')[];
+    plan?: boolean;
+    threshold?: number;
+    maxStoriesPerComponent?: number;
+}, run?: typeof import('@bridge-ds/visual').runImpact): Promise<{
+    summary: string;
+    base: {
+        ref: string;
+        sha: string;
+    };
+    head: {
+        ref: string;
+        sha: string;
+    };
+    counts: import("@bridge-ds/visual").Summary;
+    selection: {
+        tokens: number;
+        directTokens: string[];
+        components: {
+            id: string;
+            why: string | undefined;
+        }[];
+        stories: number;
+        fallback: string | null;
+        app: {
+            include: boolean;
+            reason: string;
+        };
+    };
+    changed: {
+        error?: string | undefined;
+        composite?: string | undefined;
+        label: string;
+        mode: string;
+        status: import("@bridge-ds/visual").ShotStatus;
+        percent: number;
+        boxes: number;
+    }[];
+    outDir: string;
+    manifest: string;
+    next: string;
+}>;
+/** Audit a product folder or file (local only): adoption metrics, top files, top fixes, and findings for one file. */
+export declare function auditOp(ctx: BridgeContext, a: {
+    path: string;
+    baseline?: string;
+    label?: string;
+    limit?: number;
+    findings?: boolean;
+}): Promise<{
+    next: string;
+    findings?: {
+        file: string;
+        values: {
+            use?: string | undefined;
+            confidence?: import("@bridge-ds/core/audit").Confidence | undefined;
+            property?: string | undefined;
+            line: number;
+            value: string;
+            category: import("@bridge-ds/core/audit").FindingCategory;
+        }[];
+        components: {
+            use?: string | undefined;
+            line: number;
+            name: string;
+            kind: "foreign" | "native" | "recreated";
+            library: string;
+        }[];
+    }[] | undefined;
+    byCategory: Partial<Record<import("@bridge-ds/core/audit").FindingCategory, import("@bridge-ds/core/audit").CategoryCount>>;
+    components: {
+        ds: Record<string, number>;
+        foreign: {
+            [k: string]: {
+                instances: number;
+                top: string[];
+            };
+        };
+        native: Record<string, number>;
+        recreated: {
+            name: string;
+            file: string;
+            line: number;
+            instances: number;
+        }[];
+    };
+    topFiles: {
+        path: string;
+        hardcoded: number;
+        otherComponents: number;
+        tokenUsages: number;
+        dsComponents: number;
+    }[];
+    topFixes: ({
+        confidence: import("@bridge-ds/core/audit").Confidence;
+        mode?: string | undefined;
+        use: string;
+        token: string;
+        tokenValue: string;
+        value: string;
+        category: import("@bridge-ds/core/audit").FindingCategory;
+        count: number;
+    } | {
+        use: null;
+        value: string;
+        category: import("@bridge-ds/core/audit").FindingCategory;
+        count: number;
+    })[];
+    sinceBaseline?: {
+        tokenAdoption: {
+            before: number | null;
+            after: number | null;
+            delta: number | null;
+        };
+        componentAdoption: {
+            before: number | null;
+            after: number | null;
+            delta: number | null;
+        };
+        hardcoded: {
+            before: number;
+            after: number;
+            delta: number;
+        };
+        improved: number;
+        regressed: {
+            path: string;
+            before: number;
+            after: number;
+        }[];
+    } | undefined;
+    target: string;
+    files: number;
+    metrics: import("@bridge-ds/core/audit").AuditMetrics;
+}>;