@bridge-ds/core 0.13.0 → 0.16.0

package/dist/snapshot.d.ts

@@ -0,0 +1,137 @@
+import type { AuditMetrics, AuditReport } from './audit/types';
+import type { ContrastPairResult } from './contrast-model';
+import type { SpecCoverage } from './component-spec';
+import { type RepoSource } from './repo-source';
+import type { RepoModel } from './repo-model';
+export declare const SNAPSHOT_SCHEMA_VERSION = 1;
+/** Branch the bridge-data workflow publishes to, and the files on it. */
+export declare const SNAPSHOT_BRANCH = "bridge-data";
+export declare const SNAPSHOT_FILE = "snapshot.json";
+export declare const SNAPSHOT_AUDITS_DIR = "audits";
+/** Above this, a snapshot is refused (a published file the browser downloads whole). */
+export declare const SNAPSHOT_MAX_BYTES = 5000000;
+/** One adoption audit: the summary lives in snapshot.json, the full report in audits/<id>.json next to it. */
+export interface SnapshotAudit {
+    id: string;
+    /** Path of the full report on the bridge-data branch ("audits/admin.json"). */
+    path: string;
+    label?: string;
+    generatedAt: string;
+    target: {
+        path: string;
+        files: number;
+    };
+    metrics: AuditMetrics;
+}
+/** A contrast pair as computed when the snapshot was written, without the token rows (the model has them). */
+export type SnapshotContrastPair = Omit<ContrastPairResult, 'fgToken' | 'bgToken'>;
+/** Counts for a header or a card, readable without loading the model. */
+export interface SnapshotSummary {
+    tokens: number;
+    /** Null when the component scan was skipped. */
+    components: number | null;
+    contrast: {
+        pairs: number;
+        checks: number;
+        failing: number;
+    };
+    /** Components in Figma (generated or drafted) out of the visual ones, null without a specs file. */
+    figma: {
+        inFigma: number;
+        visual: number;
+    } | null;
+}
+export interface RepoSnapshot {
+    kind: 'bridge-snapshot';
+    schemaVersion: typeof SNAPSHOT_SCHEMA_VERSION;
+    tool: {
+        name: 'bridge';
+        version: string;
+    };
+    generatedAt: string;
+    repo: {
+        owner: string;
+        name: string;
+        branch: string;
+    };
+    /** Commit the snapshot was computed from. Fresh when it equals the default branch head. */
+    sourceSha: string;
+    /** Commit date of sourceSha (ISO), when known. */
+    committedAt?: string;
+    /** Every path the model listed (token root, components dir), so list() answers as the repository did. */
+    paths: string[];
+    /** Bodies of the files the model read, keyed by repo-relative path. */
+    files: Record<string, string>;
+    /**
+     * Figma coverage of component-specs.json without the specs themselves (the file is over 1 MB here, too big for
+     * the GitHub contents source). Null when the repository has no specs file.
+     */
+    figma: {
+        path: string;
+        generated?: string;
+        coverage: SpecCoverage[];
+    } | null;
+    summary: SnapshotSummary;
+    /** Contrast results as computed when the snapshot was written (the model recomputes the same from files). */
+    contrast: {
+        path?: string;
+        pairs: SnapshotContrastPair[];
+    };
+    audits: SnapshotAudit[];
+    /** What could not be read when the snapshot was written. */
+    problems: string[];
+    /**
+     * The global stylesheet globs the model read (components.styles), their files among `files`. Absent from a snapshot
+     * written before Bridge read global stylesheets: a reader then reads those files from the repository.
+     */
+    styles?: string[];
+}
+export declare class SnapshotError extends Error {
+}
+/** Validates a snapshot (text or parsed JSON). Throws SnapshotError naming the first problem. */
+export declare function parseSnapshot(input: string | unknown): RepoSnapshot;
+/** True when the snapshot was computed from `headSha` (the default branch head): use it instead of a live read. */
+export declare const snapshotIsFresh: (snapshot: Pick<RepoSnapshot, "sourceSha">, headSha: string | undefined) => boolean;
+/**
+ * A RepoSource over a snapshot. The Figma specs path serves a compact file with the coverage only (no component
+ * specs), so the model reads the coverage and leaves `specs.file` null.
+ */
+export declare function snapshotSource(snapshot: RepoSnapshot): RepoSource;
+/**
+ * Wraps a source and records what it lists and reads, so a snapshot carries exactly the files the model needs and
+ * nothing else of the repository.
+ */
+export declare function recordingSource(source: RepoSource): {
+    source: RepoSource;
+    paths: Set<string>;
+    files: Map<string, string>;
+};
+/** Summary of an audit report for snapshot.json; the full report is written to `path`. */
+export declare function snapshotAudit(id: string, report: AuditReport): SnapshotAudit;
+/** A safe audit id from a label or path ("apps/admin/src" -> "apps-admin-src"). */
+export declare const auditId: (s: string) => string;
+export interface BuildSnapshotInput {
+    model: RepoModel;
+    /** From recordingSource(): what loadRepoModel listed and read. */
+    paths: Iterable<string>;
+    files: Map<string, string> | Record<string, string>;
+    version: string;
+    branch?: string;
+    committedAt?: string;
+    generatedAt?: string;
+    audits?: SnapshotAudit[];
+}
+/** Counts of a model for the snapshot summary. */
+export declare function snapshotSummary(model: RepoModel): SnapshotSummary;
+/** Assembles the snapshot from a model and the files it was read from. The specs file becomes the coverage list. */
+export declare function buildSnapshot(input: BuildSnapshotInput): RepoSnapshot;
+/** llms.txt next to snapshot.json on the bridge-data branch: the published design system in plain text, for agents. */
+export declare const SNAPSHOT_LLMS_FILE = "llms.txt";
+/** Above this many tokens, llms.txt lists the first ones and points at snapshot.json for the rest. */
+export declare const LLMS_MAX_TOKENS = 600;
+/**
+ * The design system of a snapshot as llms.txt (https://llmstxt.org): what it is, every token with its CSS variable and
+ * values per theme, and every component with its usage guidance. Written by `bridge snapshot`; the hosted Library
+ * links to it. Pure: the model the snapshot was computed from goes in, text comes out.
+ */
+export declare function snapshotLlmsTxt(model: RepoModel, snapshot: Pick<RepoSnapshot, 'repo' | 'sourceSha' | 'committedAt' | 'generatedAt'>): string;

package/dist/token-rows.d.ts

@@ -0,0 +1,122 @@
+import { type BridgeConfig } from './config';
+/** Token tiers of the rows, in resolution order: primitive <- brand <- semantic <- component. Density sits beside semantic. */
+export type TokenRowTier = 'primitive' | 'brand' | 'semantic' | 'density' | 'component';
+type Json = Record<string, unknown>;
+export interface RawTokenEntry {
+    path: string[];
+    type: string;
+    value: unknown;
+    description?: string;
+    /** DTCG $deprecated: true, or a string explaining what to use instead. */
+    deprecated?: boolean | string;
+    /** Repo-relative file the token is declared in. */
+    file: string;
+}
+export interface PrimitiveRow {
+    path: string;
+    segments: string[];
+    type: string;
+    /** Resolved CSS value. */
+    css: string;
+    hex?: string;
+    cssVar: string;
+    figma: string;
+    description?: string;
+    deprecated?: boolean | string;
+    raw: unknown;
+    file: string;
+}
+export interface TokenRowMode {
+    /** First alias target, or null when the value is literal. */
+    alias: string | null;
+    /** Every alias hop, from the token to the final primitive (palette roles included). */
+    chain: string[];
+    css: string;
+    hex?: string;
+}
+export interface TokenRow {
+    path: string;
+    segments: string[];
+    type: string;
+    cssVar: string;
+    figma: string;
+    description?: string;
+    /** e.g. "color.action" or "elevation". */
+    group: string;
+    deprecated?: boolean | string;
+    tier: Exclude<TokenRowTier, 'primitive'>;
+    /** Source file(s) the token is declared in, repo-relative. */
+    file: string;
+    /** Values per theme in the default brand and default density. */
+    modes: Record<string, TokenRowMode>;
+    /** Values per brand x theme (default density). */
+    brands: Record<string, Record<string, TokenRowMode>>;
+    /** Density tokens only: value per density. */
+    densities?: Record<string, TokenRowMode>;
+    /** True when the brand x theme values differ from the default brand. */
+    brandSpecific: boolean;
+}
+/** Brand, theme and density lists the rows are computed for, with their defaults and display names. */
+export interface TokenRowAxes {
+    brands: string[];
+    defaultBrand: string;
+    /** Display name per brand: the name a brand file records ($extensions dev.bridge.brand.name), else the slug in title case. */
+    brandLabels: Record<string, string>;
+    themes: string[];
+    densities: string[];
+    defaultDensity: string;
+}
+/** Repo-relative token files the rows read, from the tier folders of the config. */
+export interface TokenRowFiles {
+    primitivesDir: string;
+    semanticDir: string;
+    brandsDir: string;
+    densityDir: string;
+    componentsDir: string;
+    baseFile: string;
+    semanticFile(theme: string): string;
+    brandFile(brand: string): string;
+    overrideFile(brand: string, theme: string): string;
+    densityFile(density: string): string;
+}
+export interface TokenRows extends TokenRowAxes {
+    primitives: PrimitiveRow[];
+    /** Semantic tier: themed (one file per theme) and theme-independent (base). */
+    semantic: TokenRow[];
+    /** Brand tier: palette, radius and font roles per brand. */
+    brand: TokenRow[];
+    density: TokenRow[];
+    component: TokenRow[];
+    /** Every non-primitive token: brand, semantic, density, component. */
+    all: TokenRow[];
+    /** Repo-relative paths of every token source file, in tier order (what the "last updated" line watches). */
+    sources: string[];
+}
+/** Brand, theme and density lists from bridge.config.json, as the docs pages iterate them. */
+export declare function tokenRowAxes(config: BridgeConfig, readText?: (path: string) => string | undefined): TokenRowAxes;
+/** The token files of each tier, repo-relative, from the config's tokens.root and tier folders. */
+export declare function tokenRowFiles(config: BridgeConfig): TokenRowFiles;
+/** Flattens one DTCG document into raw tokens, inheriting $type from groups. */
+export declare function flattenTokenFile(node: Json, file: string, path?: string[], inheritedType?: string): RawTokenEntry[];
+/** CSS text (and hex for colors) of a literal DTCG value. */
+export declare function tokenValueCss(type: string, value: unknown): {
+    css: string;
+    hex?: string;
+};
+/** CSS variable of a token path ("color.bg.default" segments -> "--color-bg-default"). */
+export declare const tokenRowCssVar: (segments: string[]) => string;
+/** Figma variable name of a token path. */
+export declare const tokenRowFigmaName: (segments: string[]) => string;
+/**
+ * Builds the rows from the token files of a repo. `readText` returns a repo-relative file body (undefined when
+ * missing); `listFiles` returns the repo-relative files directly inside a directory. Throws on an alias that does not
+ * resolve and on a themed token missing from another theme, as the token build does.
+ */
+export declare function buildTokenRows(config: BridgeConfig, readText: (path: string) => string | undefined, listFiles: (dir: string) => string[]): TokenRows;
+/** Every CSS variable the rows define: cssVar -> token path, tier and type. */
+export declare function tokenRowIndex(rows: Pick<TokenRows, 'primitives' | 'all'>): Map<string, {
+    path: string;
+    kind: TokenRowTier;
+    type: string;
+}>;
+export {};

package/dist/try-in-product.d.ts

@@ -12,5 +12,8 @@ export declare function productPreview(apps: PreviewApps, ctx: {
     sha: string;
     fromFork?: boolean;
 }, sources: BranchPreviewSources): string | null;
-/** The preview with the toolbar on, at that screen (shop and theme in the query, the hash route ra-core reads), else home. */
+/**
+ * The preview with the toolbar on, at that screen (shop and theme in the query, the hash route ra-core reads), else home.
+ * Only http(s) previews: anything else (a javascript: or data: URL in a hostile comment) gives ''.
+ */
 export declare function tryInProductUrl(preview: string, pr: number, screen: ProductScreen | null): string;

package/package.json

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