@bridge-ds/core 0.17.0 → 0.19.0

package/bridge.config.schema.json

@@ -13,6 +13,12 @@
       "const": 1,
       "description": "Config format version."
     },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 60,
+      "description": "The team's display name, shown in Studio, the Library and invitations (\"Acme Design\"). Absent: Bridge names the team after its repository."
+    },
     "repo": {
       "description": "GitHub repository. Pull requests target defaultBranch; Bridge never writes to it.",
       "oneOf": [
@@ -700,6 +706,16 @@
         }
       }
     },
+    "demo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["viewer"],
+      "description": "A public demo's persona, read by Bridge's own demo repositories only: who a visitor without an account stands in for on the demo home (\"Good morning, Dana.\"). Ignored on any other repository.",
+      "properties": {
+        "viewer": { "type": "string", "minLength": 1, "description": "The persona's first name, for example \"Dana\"." },
+        "role": { "type": "string", "description": "What they do, for example \"DS lead\"." }
+      }
+    },
     "visualImpact": {
       "type": "object",
       "additionalProperties": false,

package/dist/activity.d.ts

@@ -0,0 +1,207 @@
+import { type FetchLike } from './github-client';
+import type { BridgeConfig } from './config';
+import { type HistoryReport } from './history';
+import { type RequestKind, type RequestStatus } from './requests';
+import type { RiskTier } from './risk';
+import type { SuggestionKind, SuggestionPayloadV1, SuggestionStatus } from './suggestions';
+export declare const ACTIVITY_SCHEMA_VERSION = 1;
+/** Next to snapshot.json on the bridge-data branch. */
+export declare const ACTIVITY_FILE = "activity.json";
+/** Above this, the recorded reads are dropped heaviest first (trees, then older branches) until it fits. */
+export declare const ACTIVITY_MAX_BYTES = 3000000;
+/** A guest reads activity.json while it is younger than this; older, the Studio reads GitHub live. */
+export declare const ACTIVITY_MAX_AGE_MS: number;
+/** How much one activity.json carries. Each is a count of items, newest first. */
+export declare const ACTIVITY_LIMITS: {
+    /** Open pull requests recorded in full (the page of each; the list carries every open one). */
+    readonly branches: 30;
+    /** Open suggestions read with their comments (parsed payload, counted approvals). */
+    readonly suggestions: 30;
+    /** Request issues listed (open and closed); open ones are read with their comments. */
+    readonly requests: 30;
+    /** Merged pull requests summarized. */
+    readonly merged: 20;
+    /** Token history entries (core loadGitHubHistory limit). */
+    readonly history: 20;
+    /** History entries whose two commits' file lists are recorded, so their before/after opens without the API. */
+    readonly historyTrees: 10;
+};
+export type ActivityLimits = {
+    [K in keyof typeof ACTIVITY_LIMITS]: number;
+};
+/** One GitHub answer: its status (200, or 404 for a read that finds nothing) and its JSON body, trimmed. */
+export interface ActivityResponse {
+    status: number;
+    body: unknown;
+}
+export interface ActivityBranch {
+    number: number;
+    title: string;
+    author: string;
+    url: string;
+    branch: string;
+    base: string;
+    headSha: string;
+    baseSha: string;
+    state: 'open' | 'draft';
+    labels: string[];
+    /** Risk tier from the labels, the body or the files (review-gate effectiveTier); null when none says. */
+    tier: RiskTier | null;
+    createdAt: string;
+    updatedAt: string;
+    /** Conversation plus line comments. Null when the branch was not read in full (over the limit). */
+    comments: number | null;
+    /** Files the branch changes, and the token files among them (the token diff opens from them). Null: not read. */
+    files: {
+        changed: number;
+        tokens: string[];
+    } | null;
+    /** Previews built for the head commit (commit statuses with a link, success only). */
+    previews: {
+        context: string;
+        url: string;
+    }[];
+    /** Combined check state of the head commit. */
+    checks: 'success' | 'failure' | 'pending' | 'none' | null;
+}
+export interface ActivitySuggestion {
+    number: number;
+    title: string;
+    author: string;
+    url: string;
+    createdAt: string;
+    kind: SuggestionKind | null;
+    status: SuggestionStatus;
+    labels: string[];
+    comments: number | null;
+    /** The parsed suggestion (null when its block does not parse). */
+    payload: SuggestionPayloadV1 | null;
+    approvers: string[];
+}
+export interface ActivityRequest {
+    number: number;
+    title: string;
+    author: string;
+    url: string;
+    state: 'open' | 'closed';
+    status: RequestStatus;
+    kind: RequestKind | null;
+    component: string | null;
+    labels: string[];
+    createdAt: string;
+}
+export interface ActivityMerged {
+    number: number;
+    title: string;
+    author: string;
+    url: string;
+    mergedAt: string;
+    labels: string[];
+    tier: RiskTier | null;
+}
+export interface RepoActivity {
+    kind: 'bridge-activity';
+    schemaVersion: typeof ACTIVITY_SCHEMA_VERSION;
+    tool: {
+        name: 'bridge';
+        version: string;
+    };
+    generatedAt: string;
+    repo: {
+        owner: string;
+        name: string;
+        branch: string;
+    };
+    /** Default branch head when it was written. */
+    headSha: string;
+    branches: ActivityBranch[];
+    suggestions: ActivitySuggestion[];
+    requests: ActivityRequest[];
+    merged: ActivityMerged[];
+    /** Token history of the default branch (core HistoryReport), null when it could not be read. */
+    history: HistoryReport | null;
+    /** GitHub REST answers by activityKey (path relative to api.github.com, query sorted). */
+    responses: Record<string, ActivityResponse>;
+    /** What was left out to stay within the limits, in words. */
+    truncated: string[];
+    /** What could not be read. */
+    problems: string[];
+}
+export declare class ActivityError extends Error {
+}
+/**
+ * The key of a GitHub REST read: the path relative to api.github.com with the query parameters sorted, and the
+ * owner and repository (or user) lowercased, since GitHub reads them without case. Null for any other host.
+ */
+export declare function activityKey(url: string): string | null;
+/**
+ * A GitHub answer without what no page reads: API links, node ids, diffs, reactions, the repository objects nested in
+ * a pull request's head and base (name, owner and fork kept), and user objects beyond login, avatar and type. A tree
+ * keeps path, type and sha per entry. Strings longer than 60 000 characters are cut.
+ */
+export declare function trimGitHub(value: unknown, key?: string): unknown;
+/** What a recordingFetch shaper returns for a read it should not keep. */
+export declare const SKIP: unique symbol;
+/**
+ * The paths of a tree the Studio reads from a recorded tree: token files and the contrast checks (the branch token
+ * diff), bridge.config.json, changesets, and the CHANGELOG.md and package.json the history reads. Every other entry is
+ * left out of activity.json, which keeps a tree at a few kilobytes instead of a whole repository listing.
+ */
+export declare function activityTreeFilter(config: BridgeConfig): (path: string) => boolean;
+/** The shaper collectActivity records with: trees filtered (activityTreeFilter), compares to what a branch page reads. */
+export declare function activityShaper(config: BridgeConfig): (key: string, body: unknown) => unknown | typeof SKIP;
+/** Changes listed per history entry; an import of hundreds of tokens keeps its counts and its first changes. */
+export declare const HISTORY_MAX_CHANGES = 100;
+/** A history report with each entry's change and reason lists capped (counts stay whole). */
+export declare function capHistory(report: HistoryReport, max?: number): HistoryReport;
+/**
+ * Wraps a fetch and records every GitHub REST GET that answers 200 or 404 with JSON, trimmed, under its activityKey.
+ * Reads with another media type (raw file bodies) pass through unrecorded.
+ */
+export declare function recordingFetch(fetchImpl: FetchLike, into: Map<string, ActivityResponse>, shape?: (key: string, body: unknown) => unknown | typeof SKIP): FetchLike;
+export interface CollectActivityInput {
+    /** fetch for api.github.com (the token goes in `token`). */
+    fetch: FetchLike;
+    token: string;
+    owner: string;
+    repo: string;
+    /** The repository's Bridge config (tokens root, governance, changesets): history and suggestion approvals read it. */
+    config: BridgeConfig;
+    version: string;
+    generatedAt?: string;
+    /**
+     * The activity published last time. Its history (and the file lists recorded for it) is kept when the default
+     * branch head has not moved, which saves most of the reads of a run on a schedule or a pull request event.
+     */
+    previous?: RepoActivity | null;
+    limits?: Partial<ActivityLimits>;
+}
+/**
+ * Reads the team's activity from GitHub: the same reads, with the same paths, as the hosted Studio's guest pages
+ * (Home, Branches and each open branch, Review, History, suggestions, requests), recorded, plus the summaries. A read
+ * that fails is noted in `problems` and the rest goes on; an exhausted hourly limit stops the reading there.
+ */
+export declare function collectActivity(input: CollectActivityInput): Promise<RepoActivity>;
+/** Bytes of the activity as written. */
+export declare const activityBytes: (a: RepoActivity) => number;
+/**
+ * Keeps the activity under `max` bytes: drops the recorded file lists (trees) first, then the pages of the least
+ * recently updated branches, then every recorded read. The summaries always stay. Says what it dropped in `truncated`.
+ */
+export declare function fitActivity(activity: RepoActivity, max?: number): RepoActivity;
+/** Validates an activity (text or parsed JSON). Throws ActivityError naming the first problem. */
+export declare function parseActivity(input: string | unknown): RepoActivity;
+/** Milliseconds since the activity was written (never negative). */
+export declare const activityAge: (a: Pick<RepoActivity, "generatedAt">, now?: number) => number;
+/** True while a guest should read the activity instead of GitHub: written for this repository, and recently. */
+export declare function activityIsUsable(a: Pick<RepoActivity, 'generatedAt' | 'repo'>, team: {
+    owner: string;
+    repo: string;
+}, now?: number, maxAge?: number): boolean;
+/**
+ * The recorded answer to a GitHub REST GET, or undefined when the activity did not record it (read it live). Only
+ * reads of the activity's own repository (and the user accounts it recorded) are answered.
+ */
+export declare function activityAnswer(a: Pick<RepoActivity, 'responses' | 'repo'>, url: string): ActivityResponse | undefined;
+/** "activity.json" on the bridge-data branch of a public repository, on the raw host (no API quota). */
+export declare const activityRawUrl: (owner: string, repo: string) => string;

package/dist/audit/index.js

@@ -1,6 +1,6 @@
-import { i as isAuditable, a as auditFile } from "../report-DVEmUr0p.js";
-import { A, b, c, C, D, d, F, I, L, e, M, N, f, g, h, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, E, G, H, J, K, O, P, Q, R, S, T, U, V, W, X, Y, Z } from "../report-DVEmUr0p.js";
-import { p as pieceId, a as proposedTokenPath, t as tokenLabel } from "../prod-branch-DenQkr_e.js";
+import { i as isAuditable, a as auditFile } from "../report-DFPKygfk.js";
+import { A, b, c, C, D, d, F, I, L, e, M, N, f, g, h, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, E, G, H, J, K, O, P, Q, R, S, T, U, V, W, X, Y, Z } from "../report-DFPKygfk.js";
+import { p as pieceId, a as proposedTokenPath, t as tokenLabel } from "../prod-branch-Bdx_2bRQ.js";
 const lines = (text) => text.split(/\r?\n/);
 function lineBag(text) {
   const bag = /* @__PURE__ */ new Map();

package/dist/audit/report.d.ts

@@ -44,8 +44,23 @@ export interface CssFixEdit {
     to: string;
     token: string;
 }
-/** Safe autofix for a CSS/SCSS/Less file: exact token matches become var(--token). Returns the edits and the new text. */
-export declare function planCssFixes(text: string, lang: 'css' | 'scss' | 'less', ds: DesignSystemIndex): {
+/** A value the fix leaves as it is, like the audit leaves it out of the counts: an ignore comment or the allowlist. */
+export interface CssFixKept {
+    line: number;
+    column: number;
+    from: string;
+    reason: string;
+    via: 'comment' | 'allowlist';
+}
+/**
+ * Safe autofix for a CSS/SCSS/Less file: exact token matches become var(--token). Returns the edits and the new text.
+ * The same exceptions as the audit: a `bridge-audit-ignore-next-line: reason` comment on the line above, and the
+ * allowlist entries of this file, keep the value (listed in `kept`).
+ */
+export declare function planCssFixes(text: string, lang: 'css' | 'scss' | 'less', ds: DesignSystemIndex, opts?: {
+    allowlist?: AllowlistEntry[] | undefined;
+}): {
     edits: CssFixEdit[];
     output: string;
+    kept: CssFixKept[];
 };

package/dist/branch-actions.d.ts

@@ -1,10 +1,15 @@
 import type { GitHubClient, Review } from './github-client';
 import { type MergeMethod, type MissingApproval } from './review-gate';
-/** Merges a branch at the head the person saw (GitHub refuses when it moved meanwhile). Studio's Merge button: squash. */
+/**
+ * Merges a branch at the head the person saw (GitHub refuses when it moved meanwhile). Studio's Merge button: squash.
+ * `draft`: GitHub still calls it a draft though the gate reads it ready (core isDraft, `drafted-by-claude`), so it is
+ * marked ready for review first: GitHub never merges a draft.
+ */
 export declare function mergeOnGitHub(gh: GitHubClient, input: {
     number: number;
     headSha: string;
     method?: MergeMethod | undefined;
+    draft?: boolean | undefined;
 }): Promise<{
     sha: string;
 }>;
@@ -28,6 +33,7 @@ export declare function overrideMergeOnGitHub(gh: GitHubClient, input: {
     reason: string;
     missing: MissingApproval[];
     method: MergeMethod;
+    draft?: boolean | undefined;
 }): Promise<{
     sha: string;
     commentUrl: string;

package/dist/build-requests-github.d.ts

@@ -0,0 +1,25 @@
+import { type BuildRequestInput, type BuildRequestView, type LibraryArrival, type PublishOutcome } from './build-requests';
+import type { GitHubClient } from './github-client';
+/**
+ * Files a build request: one issue, labeled component-change (the bridge-jira Action mirrors it to Jira when set up),
+ * bridge-build, the request kind and the source. `labels` and `assignees` come from integrations.requests. Returns the
+ * outcome the plugin shows ("Build request sent").
+ */
+export declare function createBuildRequestOnGitHub(gh: GitHubClient, input: BuildRequestInput, opts?: {
+    labels?: string[] | undefined;
+    assignees?: string[] | undefined;
+    componentUrl?: string | undefined;
+}): Promise<PublishOutcome>;
+/**
+ * Every build request with its status, read from GitHub: the component-change and bridge-build issues, and the pull
+ * requests that close them or are library branches from Figma. Two to three list calls, no per-item reads.
+ */
+export declare function listBuildRequestsOnGitHub(gh: GitHubClient, opts?: {
+    now?: Date | number | undefined;
+    nameOf?: ((login: string) => string) | undefined;
+}): Promise<BuildRequestView[]>;
+/**
+ * Where a token push the plugin published as `shipped` stands: poll it until `final` ("In the library", or "Held for a
+ * developer" / "Not shipped"). Reads the pull request, its checks and its reviews.
+ */
+export declare function libraryArrivalOnGitHub(gh: GitHubClient, n: number): Promise<LibraryArrival>;