@bridge-ds/core 0.13.0 → 0.15.0

package/dist/repo-access.d.ts

@@ -0,0 +1,66 @@
+import { GitHubClient, type RepoInfo } from './github-client';
+/**
+ * - anonymous-public: not signed in, the repository is public (read-only Studio).
+ * - anonymous-unknown: not signed in, GitHub answers 404 (private or missing: GitHub does not say which).
+ * - no-access: signed in, GitHub answers 404 (no such repo, not a collaborator, or the App is not installed on it).
+ * - not-installed: signed in with explicit permission (triage or more) on a public repository, and the App's
+ *   installations do not cover it: it is not installed there.
+ * - outside-contributor: signed in, public repository, read access only, and no App installation lists it. GitHub
+ *   lists installations only where the user has explicit permission, so this may be a non-collaborator of a repo
+ *   where Bridge is installed: never say "not installed" here. Browse only; ask an admin for access.
+ * - reader: pull or triage. Browse, comment, file suggestions.
+ * - writer: push or maintain. Plus direct changes.
+ * - admin: admin. Plus settings and protection.
+ */
+export type RepoAccessState = 'anonymous-public' | 'anonymous-unknown' | 'no-access' | 'not-installed' | 'outside-contributor' | 'reader' | 'writer' | 'admin';
+/** The viewer's permissions on a repository, as GET /repos returns them. */
+export type RepoPermissions = NonNullable<RepoInfo['permissions']>;
+export interface AccessFacts {
+    /** A token was sent. */
+    signedIn: boolean;
+    /** GET /repos answered 200 (false on 404). */
+    visible: boolean;
+    /**
+     * An installation of the App the user can reach covers the repository; null or undefined when not checked
+     * (personal token) or GitHub would not say.
+     */
+    installed?: boolean | null | undefined;
+    /** GET /repos said the repository is private. */
+    private?: boolean | undefined;
+    permissions?: RepoPermissions | undefined;
+}
+/** The access state from the facts (section 3.3 table). */
+export declare function accessState(f: AccessFacts): RepoAccessState;
+/**
+ * True when `state` grants at least what `min` grants: 'reader' (suggest, comment), 'writer' (direct changes),
+ * 'admin' (settings). The read-only states rank as 'anonymous-public'; the closed ones rank lowest.
+ */
+export declare function accessAtLeast(state: RepoAccessState, min: 'anonymous-public' | 'reader' | 'writer' | 'admin'): boolean;
+export interface RepoAccess {
+    state: RepoAccessState;
+    owner: string;
+    repo: string;
+    /** Undefined when GitHub did not show the repository. */
+    private: boolean | undefined;
+    defaultBranch: string | undefined;
+    permissions: RepoPermissions | undefined;
+    /** The App installation that gives the user this repository, when checked and found. */
+    installationId?: number | undefined;
+    /** With a Direct App client: whether that App is installed for the user on the repository (null when unknown). */
+    directInstalled?: boolean | null | undefined;
+}
+export interface ResolveAccessOptions {
+    /**
+     * The client's token is a GitHub App user-to-server token: check its installations (2 or 3 calls). Leave off for a
+     * personal token or anonymous reads; the state then comes from GET /repos alone.
+     */
+    app?: boolean;
+    /** A client with the Direct App's token, to learn whether that App is installed too (changes: "direct"). */
+    direct?: GitHubClient;
+}
+/**
+ * Reads what the client's token (or no token) can do on the client's repository. With `app`, the client's token must
+ * be a user token of the signing-in App (each App lists only its own installations). A 404 is a state, not an error;
+ * a rejected token (401) and an exhausted rate limit (429) are thrown for the caller to handle as today.
+ */
+export declare function resolveRepoAccess(client: GitHubClient, opts?: ResolveAccessOptions): Promise<RepoAccess>;

package/dist/repo-model.d.ts

@@ -0,0 +1,142 @@
+import { type BridgeConfig, type ChangesMode } from './config';
+import { type ScannedComponent } from './component-scan';
+import { type ComponentSpecsFile, type SpecCoverage } from './component-spec';
+import { type ContrastPairResult, type ContrastPairSpec } from './contrast-model';
+import { type ProductConfig } from './products';
+import { type RepoSource, type RepoSourceRef } from './repo-source';
+import type { IntegrationsConfig } from './requests';
+import type { Rights, VisualImpactMode } from './rights';
+import { type TokenRows, type TokenRowTier } from './token-rows';
+/** Paths used when bridge.config.json does not name them: where this repo kept them before the config did. */
+export declare const REPO_MODEL_DEFAULTS: {
+    readonly tokensRoot: "packages/tokens/src";
+    readonly componentsDir: "packages/react/src/components";
+    readonly componentSpecs: "packages/react/component-specs.json";
+    /** Optional token usage notes (group -> sentence), relative to tokens.root, when tokens.usage is not set. */
+    readonly tokensUsage: "usage.json";
+    readonly repo: {
+        readonly owner: "peterbono";
+        readonly repo: "ai-design-system-demo";
+        readonly defaultBranch: "main";
+    };
+};
+/** The repository settings the site and Studio act on (roles, owners, mode), derived from bridge.config.json. */
+export interface SiteRepo {
+    owner: string;
+    repo: string;
+    defaultBranch: string;
+    /** GitHub logins that count as design and tech owners for Tier 3 approvals. Empty: any two distinct approvers. */
+    owners: {
+        design: string[];
+        tech: string[];
+    };
+    /** Who may merge past missing approvals from Reviews, with a reason. `allowed` empty: no override. */
+    override: {
+        allowed: string[];
+        requireReason: boolean;
+        minReasonLength: number;
+    };
+    /** Which owner group approves design, approves tech and ships. null: not set. */
+    rights: Rights | null;
+    /** governance.soloOwnerCanApproveBoth: the only owner's approval covers design and tech. Default false. */
+    soloOwnerCanApproveBoth: boolean;
+    /** Visual before and after: on every pull request (auto) or when someone asks (on-demand, label visual-check). */
+    visualImpact: {
+        mode: VisualImpactMode;
+    };
+    /** Token root in the repo. */
+    tokensRoot: string;
+    /** Where component change requests go besides the GitHub issue. Empty: GitHub only. */
+    integrations: IntegrationsConfig;
+    /** The apps that consume the design system, the library being the default. */
+    products: ProductConfig[];
+    /** How changes reach the code: "suggest" (default) or "direct". */
+    changes: ChangesMode;
+}
+/**
+ * SiteRepo from a parsed config. `raw` (the file as parsed JSON) carries the older top-level keys loadConfig does not
+ * keep (`owner`, `defaultBranch`, `owners`); `fallback` names the repo when the config does not.
+ */
+export declare function siteRepoFromConfig(config: BridgeConfig, raw?: unknown, fallback?: {
+    owner: string;
+    repo: string;
+    defaultBranch: string;
+}): SiteRepo;
+/** The config the model uses when the repo has no bridge.config.json (or an invalid one): the defaults above. */
+export declare const defaultModelConfig: () => BridgeConfig;
+/** bridge.config.json text -> config, parsed once. Never throws: problems are returned and the defaults stand in. */
+export declare function parseModelConfig(text: string | null): {
+    config: BridgeConfig;
+    raw: unknown;
+    problems: string[];
+};
+export interface RepoModel {
+    ref: RepoSourceRef;
+    /** bridge.config.json as read, null when the repo has none. */
+    configText: string | null;
+    config: BridgeConfig;
+    site: SiteRepo;
+    /** What could not be read (invalid config, a docs.json that does not parse, an alias that does not resolve). */
+    problems: string[];
+    tokens: {
+        /** tokens.root, repo-relative. */
+        root: string;
+        /** Token file bodies keyed by path relative to tokens.root, as buildTokenSet and the token explorer read them. */
+        files: Record<string, string>;
+        rows: TokenRows;
+        /** Notes per token group (tokens.usage), null when the repo has none. */
+        usage: Record<string, string> | null;
+    };
+    contrast: {
+        /** Repo-relative checks file, undefined when the config names none. */
+        path: string | undefined;
+        specs: ContrastPairSpec[];
+        pairs: ContrastPairResult[];
+    };
+    /** Null when the scan was skipped (options.components false). */
+    components: {
+        dir: string;
+        /** Barrel file the families come from, when it exists. */
+        index: string | undefined;
+        families: {
+            name: string;
+            members: string[];
+        }[];
+        list: ScannedComponent[];
+    } | null;
+    specs: {
+        path: string;
+        /** Parsed component-specs.json, null when missing or of another version. */
+        file: ComponentSpecsFile | null;
+        /** Figma coverage entries, read even from an older file. */
+        coverage: SpecCoverage[];
+    };
+}
+export interface RepoModelOptions {
+    /** Scan components (3-4 files per component). Default true. */
+    components?: boolean;
+    /** Docs link of a token's CSS variable (the caller's routing), given its type, tier and token path. Default: none. */
+    href?: (cssVar: string, type: string, tier: TokenRowTier, path: string) => string | undefined;
+    /** Requests in flight. Default 8. */
+    concurrency?: number;
+    /**
+     * Hears how far the read has gone, in real file counts: once with every phase's total before the first body is
+     * read, then once per file settled. Phases run in order: tokens (token files, contrast checks, usage notes), then
+     * components (code, styles, stories, the index and the Figma specs), then docs (each component's docs file).
+     */
+    onProgress?: (progress: RepoModelProgress) => void;
+}
+/** The three reads of loadRepoModel, in the order they run. */
+export type RepoModelPhase = 'tokens' | 'components' | 'docs';
+export interface RepoModelProgress {
+    /** The phase being read. */
+    phase: RepoModelPhase;
+    /** Files of this phase settled so far, and in all (a phase with nothing to read reports 0 of 0). */
+    done: number;
+    total: number;
+    /** Across every phase: the bar of the whole read. `filesTotal` is known from the first report and never moves. */
+    filesDone: number;
+    filesTotal: number;
+}
+/** Reads a repo through `source` and computes its model. Never throws on repo content: see `problems`. */
+export declare function loadRepoModel(source: RepoSource, options?: RepoModelOptions): Promise<RepoModel>;