@bridge-ds/core 0.16.0 → 0.18.0

package/dist/review-gate.d.ts

@@ -149,12 +149,16 @@ export type ReviewStatusKind = 'merged' | 'closed' | 'draft' | 'ci-failing' | 'c
  */
 export declare const REVIEW_STATUS_ORDER: Record<ReviewStatusKind, number>;
 /**
- * One status chip for a pull request, from real data. Same rules and order as the pull request header
- * (lib/changes needFromDetail): lifecycle, draft, CI failing, changes requested, merge conflict, CI running, then
- * missing approvals (Tier 3 by default), then ready. `mergeable` null means GitHub has not computed it yet: the chip
- * reads "Checking" instead of an approval or "Ready to ship", so a list never says something the detail contradicts.
- * Undefined means it was not read: no conflict known. `ready` is returned only when mergeGate allows the merge.
- * Unknown CI or reviews (null, still loading or failed) never read as ready.
+ * The one status of a pull request, from real data: every surface (the Studio list, the branch page, the home, the
+ * MCP server and the CLI) derives it here, so the same branch never reads two ways. Same rules and order as the merge
+ * gate: lifecycle, draft, CI failing, changes requested, merge conflict, CI running, then missing approvals (Tier 3 by
+ * default), then ready.
+ *
+ * A repo with no automated checks (`ci.state` "none") is a calm state of its own, never "Checking" or unknown: the
+ * status comes from the approvals, as for any branch. `mergeable` null means GitHub has not computed whether it merges
+ * cleanly yet: that never hides a missing approval (it is missing either way), it only keeps "Ready to merge" back
+ * ("checking") until GitHub answers. Undefined means it was not read: no conflict known. `ready` is returned only when
+ * mergeGate allows the merge. Unknown CI or reviews (null: the read failed) never read as ready.
  */
 export declare function reviewStatusKind(input: {
     state?: string;
@@ -165,6 +169,13 @@ export declare function reviewStatusKind(input: {
     tier: RiskTier | null;
     mergeable?: boolean | null;
 }): ReviewStatusKind;
+/**
+ * The words of each status, the same in Studio, the MCP server and the CLI. "checking" only ever means GitHub is still
+ * working out whether an approved branch merges cleanly; it never stands for missing tests.
+ */
+export declare const REVIEW_STATUS_LABEL: Record<ReviewStatusKind, string>;
+/** The words of a CI summary. A repo without automated checks reads as that, calmly, never as pending or unknown. */
+export declare const CI_STATE_LABEL: Record<CiState, string>;
 export interface QueuePull extends PullStateLike {
     state: string;
     labels?: ({

package/dist/rights.d.ts

@@ -80,4 +80,23 @@ export interface VisualImpactConfig {
 export declare const DEFAULT_VISUAL_IMPACT: VisualImpactConfig;
 /** Label that asks the visual impact workflow to run in on-demand mode. */
 export declare const VISUAL_CHECK_LABEL = "visual-check";
+/** The workflow that makes the visual before and after (`bridge impact`), as its file is named in .github/workflows. */
+export declare const VISUAL_WORKFLOW_FILES: readonly string[];
+/** Where a team reads how to set up visual checks. */
+export declare const VISUAL_CHECKS_DOCS = "https://github.com/peterbono/ai-design-system-demo/blob/main/docs/GOVERNANCE.md#visual-before-and-after";
+/**
+ * Whether the repo has the visual impact workflow, from the files in .github/workflows (paths or names). Without it,
+ * neither the visual-check label nor a run "again" means anything, so Bridge offers neither: `visualImpact` in the
+ * config only says when the workflow runs, never that it exists.
+ */
+export declare function hasVisualWorkflow(files: readonly string[]): boolean;
+/**
+ * What a branch offers about visual checks: `run` (the workflow exists: the before and after, the visual-check label
+ * on demand, "runs again" after an update), `set-up` (it touches what visual checks capture but the repo has none: a
+ * calm link to the docs, never an ask), `none` (nothing visual changes). `workflow` null: not read, the old behaviour.
+ */
+export declare function visualOffer(x: {
+    touchesVisuals: boolean;
+    workflow: boolean | null;
+}): 'run' | 'set-up' | 'none';
 export declare function visualImpactProblems(raw: unknown): string[];

package/dist/suggestions-github.d.ts

@@ -2,6 +2,8 @@ import { GitHubClient, type IssueSummary, type PullRequestSummary } from './gith
 import { type SuggestionAppliedRecord, type SuggestionApprovals, type SuggestionCommentLike, type SuggestionGovernance, type SuggestionReviewEvent } from './suggestion-review';
 import { type ComposeSuggestionOptions, type ParsedSuggestion, type SuggestionKind, type SuggestionPayloadV1, type SuggestionStatus } from './suggestions';
 import type { ApprovalRole } from './review-gate';
+import { type BridgeConfig } from './config';
+import { type SuggestionApplyOp, type SuggestionApplyPlan, type SuggestionWorkspace } from './suggestion-apply';
 export interface CreatedSuggestion {
     number: number;
     url: string;
@@ -85,10 +87,51 @@ export declare function getSuggestionOnGitHub(gh: GitHubClient, n: number, gov:
     outdated?: boolean | undefined;
 }): Promise<SuggestionDetail>;
 /**
- * Keeps exactly one state label on the issue, the one the status calls for (none once closed or outdated). Best
- * effort: returns a warning sentence when the labels could not be changed.
+ * Keeps exactly one status label on the issue, the one the status calls for (suggestionLabelChanges): an open state
+ * label while open, the final label ("suggestion: applied", "suggestion: declined") once closed, the old ones removed.
+ * Best effort: returns a warning sentence when the labels could not be changed.
  */
 export declare function syncSuggestionStateLabel(gh: GitHubClient, n: number, labels: readonly string[], status: SuggestionStatus): Promise<string | null>;
+/**
+ * After a pull request merged: every Bridge suggestion it closes ("Closes #n") gets its final label, "suggestion:
+ * applied", and loses "needs review" and "applying". Issues that are not suggestions are left alone. Best effort: never
+ * throws, returns the suggestions it labelled and a warning per one it could not.
+ */
+export declare function markSuggestionsAppliedOnGitHub(gh: GitHubClient, pr: {
+    body: string | null | undefined;
+}): Promise<{
+    applied: number[];
+    warnings: string[];
+}>;
+/** The planner's workspace over the GitHub API at a ref or commit: nothing is written. */
+export declare function githubSuggestionWorkspace(gh: GitHubClient, ref: string): SuggestionWorkspace;
+/** Whether a changed repo file can change what a suggestion writes: one of its files, a token file, or the config. */
+export declare function suggestionTouches(payload: SuggestionPayloadV1, config: BridgeConfig, path: string): boolean;
+export interface SuggestionStaleness {
+    /** The head of the base branch it was checked against, or null when it could not be read. */
+    mainSha: string | null;
+    /** Main has commits since the suggestion was made. */
+    mainMoved: boolean;
+    /** Main moved and part of the change no longer applies: the value it changes is not the one it was suggested from. */
+    outdated: boolean;
+    /** The changes that conflict with main now (planSuggestionApply), empty when none or not planned. */
+    conflicts: SuggestionApplyOp[];
+    /** The dry run on main, when it ran (main moved and touched what the suggestion writes). */
+    plan: SuggestionApplyPlan | null;
+}
+/**
+ * Whether an open suggestion still applies to main (the same staleness rule for Studio, the MCP server and the CLI).
+ * Cheap first: nothing to plan when main has not moved since the suggestion's base, or moved without touching what it
+ * writes (one compare). Otherwise planSuggestionApply runs on main, nothing written, past the approvals, and any
+ * conflict makes it outdated. A read that fails says "not outdated", never a guess.
+ */
+export declare function suggestionStalenessOnGitHub(gh: GitHubClient, d: Pick<SuggestionDetail, 'parsed' | 'comments' | 'issue'>, input: {
+    config: BridgeConfig;
+    governance?: SuggestionGovernance | undefined;
+    ref?: string | undefined;
+}): Promise<SuggestionStaleness>;
+/** A suggestion's status once its staleness on main is known (withOutdated). */
+export declare function stalenessStatus(status: SuggestionStatus, staleness: Pick<SuggestionStaleness, 'outdated'> | null | undefined): SuggestionStatus;
 export interface SuggestionReviewResult {
     commentUrl: string;
     payloadSha: string;
@@ -111,8 +154,9 @@ export declare function reviewSuggestionOnGitHub(gh: GitHubClient, n: number, in
     at?: Date | undefined;
 }, gov: SuggestionGovernance): Promise<SuggestionReviewResult>;
 /**
- * Records that a suggestion is being applied (the applied marker comment) and sets the `suggestion: applying` label.
- * Called after a developer pushed the branch or opened the pull request that says "Closes #n".
+ * Records that a suggestion is being applied (the applied marker comment) and sets its status label: "suggestion:
+ * applying" while the pull request is open, "suggestion: applied" (the old labels removed) once it merged or the issue
+ * is closed as completed. Called after a developer pushed the branch or opened the pull request that says "Closes #n".
  */
 export declare function linkSuggestionPrOnGitHub(gh: GitHubClient, n: number, link: {
     pr?: number | undefined;
@@ -122,9 +166,13 @@ export declare function linkSuggestionPrOnGitHub(gh: GitHubClient, n: number, li
     payloadSha: string;
     forced?: boolean | undefined;
     at?: Date | undefined;
+    merged?: boolean | undefined;
 }): Promise<{
     warnings: string[];
+    status: SuggestionStatus;
 }>;
+/** Applied once its pull request merged or the issue is closed as completed; being applied before that. */
+export declare function appliedStatus(issue: Pick<IssueSummary, 'state' | 'stateReason'>, merged?: boolean | undefined): 'applied' | 'applying';
 /** Declines a suggestion like a request (reason comment, closed as not planned), then clears its state label. */
 export declare function declineSuggestionOnGitHub(gh: GitHubClient, n: number, reason: string, by?: string | null): Promise<{
     warnings: string[];

package/dist/suggestions.d.ts

@@ -13,6 +13,11 @@ export type SuggestionState = 'needs-review' | 'changes-requested' | 'approved'
 /** Where a suggestion stands (suggestionStatus). */
 export type SuggestionStatus = SuggestionState | 'applied' | 'declined' | 'outdated';
 export declare const SUGGESTION_STATE_LABELS: Record<SuggestionState, string>;
+/**
+ * The label a finished suggestion keeps once closed, in place of the open state labels (applied through a merged
+ * pull request or closed as completed; declined).
+ */
+export declare const SUGGESTION_FINAL_LABELS: Record<'applied' | 'declined', string>;
 export declare const SUGGESTION_STATUS_LABEL: Record<SuggestionStatus, string>;
 /** A whole-file result: the git blob sha at `base` (null: a new file), after (null: deleted), and the new content. */
 export interface SuggestionFile {
@@ -174,8 +179,27 @@ export interface SuggestionStatusInput {
  * dry run found a conflict; then the review state (changes requested, approved, needs review).
  */
 export declare function suggestionStatus(i: SuggestionStatusInput): SuggestionStatus;
-/** The state label a status keeps on the issue, or null when none should stay (closed, outdated). */
+/**
+ * Outdated wins over the review state once main moved under a suggestion and its change no longer applies (the dry run
+ * of planSuggestionApply found a conflict: the value it changes is not the one it was suggested from). Being applied,
+ * applied and declined stay as they are.
+ */
+export declare function withOutdated(status: SuggestionStatus, outdated: boolean | null | undefined): SuggestionStatus;
+/**
+ * The status label a suggestion keeps on the issue: one open state label while it is open, the final label once it is
+ * applied or declined, none while it is outdated (the review label then stays as it was).
+ */
 export declare function suggestionStateLabel(status: SuggestionStatus): string | null;
+/** Every status label Bridge manages on a suggestion issue (open states and final ones). */
+export declare const SUGGESTION_STATUS_LABELS: readonly string[];
+/**
+ * The status labels to add and remove so the issue carries exactly the one its status calls for: an applied and
+ * closed suggestion loses "needs review" and "applying" and gains "applied". Outdated keeps the labels it has.
+ */
+export declare function suggestionLabelChanges(labels: readonly string[], status: SuggestionStatus): {
+    add: string[];
+    remove: string[];
+};
 export interface SuggestionIssue {
     title: string;
     body: string;

package/dist/titles.d.ts

@@ -0,0 +1,9 @@
+/** The first letter in lower case, unless the first word is a proper name (properWord). */
+export declare function lowerFirstWord(text: string, names?: readonly string[]): string;
+/**
+ * "<subject>: <title>", the title's first letter lowered unless it starts with a proper name. A title that already
+ * starts with the subject (any case, with or without a colon) is not prefixed again: "select: keyboard focus" under
+ * Select gives "Select: keyboard focus", "Select keeps focus" stays "Select keeps focus", with the subject's own
+ * capitals. A trailing period is dropped. `names` lists other proper names to keep (component names).
+ */
+export declare function subjectTitle(subject: string, title: string, names?: readonly string[]): string;

package/package.json

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