onsystem 0.0.1 → 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,775 @@
+import { C as RuleId, D as loadConfig, E as defineConfig, O as ImportMapping, S as ResolvedRule, T as configJsonSchema, _ as VariantInfo, a as DesignSystemModel, b as RULE_IDS, c as ExampleInfo, d as Severity, f as SourceLocation, g as TokenCategory, h as Token, i as CompoundVariantInfo, l as InheritedProps, m as TextEdit, n as ComponentDocs, o as Diagnostic, p as TOKEN_CATEGORIES, r as ComponentInfo, s as DocSection, t as CheckResult, u as PropInfo, v as Config, w as RuleOptions, x as ResolvedConfig, y as LoadConfigOptions } from "./types-DJtccu3A.js";
+import ts from "typescript";
+import { Oklch } from "culori";
+import { McpServer, Transport } from "@modelcontextprotocol/server";
+//#region src/lint/analyze.d.ts
+interface ImportBinding {
+  source: string;
+  /** Imported name, `default`, or `*` for namespace imports. */
+  imported: string;
+}
+interface JsxNode {
+  node: ts.JsxElement | ts.JsxSelfClosingElement;
+  opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement;
+  closing?: ts.JsxClosingElement | undefined;
+  tagName: ts.JsxTagNameExpression;
+  /** Tag as written: `button`, `Button`, `Card.Header`. */
+  tag: string;
+  attributes: ts.JsxAttribute[];
+  hasSpread: boolean;
+  children: readonly ts.JsxChild[];
+}
+/** A run of literal class text with its absolute offset in the source. */
+interface ClassString {
+  text: string;
+  start: number;
+  /** The JSX element whose `className` this is, if any. */
+  element?: JsxNode | undefined;
+}
+interface StyleObject {
+  element: JsxNode;
+  object: ts.ObjectLiteralExpression;
+}
+interface Analysis {
+  imports: Map<string, ImportBinding>;
+  declared: Set<string>;
+  elements: JsxNode[];
+  classStrings: ClassString[];
+  styles: StyleObject[];
+}
+//#endregion
+//#region src/modules.d.ts
+/** Where an import points: a file relative to the root, or `{}` for a declared module not on disk. */
+interface ModuleLocation {
+  file?: string;
+}
+/** What a module exports by name, and the modules it re-exports wholesale (`export * from`). */
+interface ModuleExports {
+  /** Every name it exports, its own and re-exported ones. */
+  names: string[];
+  /** The names it declares itself (`export function Table`), not re-exports. */
+  declared: string[];
+  /** Files relative to the root; undefined where the specifier does not resolve. */
+  starFrom: (string | undefined)[];
+  /**
+   * Names it re-exports from another module, and under which name that module exports
+   * them: `export { Button } from "./Button"`, `export { Root as Dialog } from "./dialog"`,
+   * or an imported binding exported again. `from` is undefined where it does not resolve.
+   */
+  reexports: Map<string, {
+    from: string | undefined;
+    name: string;
+  }>;
+  /** Names it exports as a module namespace (`export * as Radio from "./radio"`), not a component. */
+  namespaces: Set<string>;
+}
+/**
+ * Finds the modules a checked file imports from the design system, and what
+ * they export, so the linter can tell a name the model left out (an excluded
+ * folder, a package built to `dist/`) from an invented one. It resolves through
+ * tsconfig `paths`, relative paths and workspace packages, reads files only
+ * when asked, and caches both. Where the root is not on disk (the website's
+ * playground), it finds nothing, and every missing name counts as invented.
+ */
+declare class ModuleResolver {
+  private readonly config;
+  private resolveFn?;
+  private readonly locations;
+  private readonly exported;
+  constructor(config: Pick<ResolvedConfig, 'root' | 'tsconfig'>);
+  /** The module `specifier` points at from `fromFile` (relative to the root). */
+  locate(specifier: string, fromFile: string): ModuleLocation | undefined;
+  /** What a module exports, read from its source without type-checking. */
+  exportsOf(file: string): ModuleExports | undefined;
+  private createResolver;
+}
+//#endregion
+//#region src/tokens/roles.d.ts
+/**
+ * What a color utility paints, which decides the tokens that fit it: `text-*`
+ * wants a foreground, `bg-*` a surface, `border-*` a border color.
+ */
+type ColorRole = 'text' | 'surface' | 'line';
+/**
+ * Token families made for one part of the UI. `sidebar-accent` has the value
+ * of `accent` and `chart-2` that of `muted-foreground`, but they only belong
+ * in a sidebar or a chart. Beyond these two, any family that is not named for
+ * a role and that at most one design-system file uses is scoped the same way:
+ * syntax-highlighting colors (`sh-class`), a chart palette (`rainbow-4`), one
+ * screen's background (`envelope-editor-background`), or a copy of Tailwind's
+ * palette (`color-red-500`).
+ */
+type ScopedFamily = string;
+//#endregion
+//#region src/tokens/css.d.ts
+/**
+ * Reads design tokens from CSS custom properties, the way shadcn/ui and
+ * Tailwind v4 projects define them:
+ *
+ * - `:root { --primary: oklch(...) }` holds the values,
+ * - `.dark { --primary: ... }` (or a dark media query / data attribute) holds modes,
+ * - `@theme inline { --color-primary: var(--primary) }` exposes them to Tailwind.
+ */
+export declare function parseCssTokens(css: string, file: string): {
+  tokens: Token[];
+  warnings: string[];
+};
+//#endregion
+//#region src/tokens/dtcg.d.ts
+interface DtcgOptions {
+  /** Prefix for generated custom property names: `ds` → `--ds-color-primary`. */
+  prefix?: string;
+}
+export declare function parseDtcgTokens(text: string, file: string, options?: DtcgOptions): {
+  tokens: Token[];
+  warnings: string[];
+};
+//#endregion
+//#region src/tokens/index.d.ts
+interface TokenSource {
+  file: string;
+  /** DTCG only: prefix for generated custom property names. */
+  prefix?: string | undefined;
+}
+export declare function loadTokens(root: string, sources: TokenSource[]): Promise<{
+  tokens: Token[];
+  warnings: string[];
+}>;
+/**
+ * DTCG files and the CSS generated from them often describe the same tokens.
+ * Merge entries that share a custom property: keep the DTCG name and
+ * description, and add the Tailwind mapping from CSS.
+ */
+export declare function mergeTokens(tokens: Token[]): Token[];
+interface ColorCandidate {
+  token: Token;
+  color: Oklch;
+  /** Values in other theme modes (`dark`), where the token has one. */
+  modes?: Record<string, Oklch>;
+}
+interface LengthCandidate {
+  token: Token;
+  px: number;
+  /** Tailwind key for the step (`3` for `p-3`, `md` for `rounded-md`), if any. */
+  key?: string;
+}
+interface Nearest<T> {
+  candidate: T;
+  distance: number;
+}
+interface ColorQuery {
+  /** What the color paints: `text-*` is best served by a foreground, `bg-*` by a surface. */
+  role?: ColorRole | undefined;
+  /** The scoped families the code is in (`sidebar` in `app-sidebar.tsx`), whose tokens then compete like any other. */
+  scopes?: ReadonlySet<ScopedFamily> | undefined;
+  /** Whether the color is a hue rather than a gray. Default: from its chroma. */
+  tinted?: boolean | undefined;
+  /** The theme mode the color applies in (`dark` for `dark:bg-*`): tokens are compared by their value there. */
+  mode?: string | undefined;
+}
+interface ColorSuggestion {
+  /** A token that can replace the color as is: close, of the same hue (or both gray), and not made for another role. */
+  match?: Nearest<ColorCandidate> | undefined;
+  /** The token to name: the match, else the nearest, preferring the same hue and the role. */
+  nearest: Nearest<ColorCandidate>;
+  /**
+   * Why the nearest token is no match: no token of its hue (or no gray), too far,
+   * made for another role, a status color whose hue is not close enough, or a
+   * token of a family scoped to another part of the UI.
+   */
+  reason?: 'far' | 'hue' | 'role' | 'status' | 'scoped' | undefined;
+  /** With reason `status`: how far apart the hues are, in degrees. */
+  hueOff?: number | undefined;
+  /** Other tokens with the nearest one's value. */
+  sameValue: Token[];
+}
+interface NearestLength extends Nearest<LengthCandidate> {
+  /** A radius so far above the scale that it means "fully rounded" (`rounded-full`). */
+  pill?: boolean;
+}
+/** Query helpers over the token list: lookups and nearest-token search. */
+export declare class TokenIndex {
+  readonly tokens: Token[];
+  readonly colors: ColorCandidate[];
+  readonly spacing: LengthCandidate[];
+  readonly radius: LengthCandidate[];
+  /** Tailwind color keys the design system defines (`primary`, `muted-foreground`). */
+  readonly colorKeys: Set<string>;
+  /** Base unit when spacing follows Tailwind's multiplier model. */
+  readonly spacingUnitPx: number | undefined;
+  private readonly spacingUnit;
+  private readonly byVar;
+  /** Families suggested only in their own part of the UI (`sidebar`, `chart`, `sh`). */
+  readonly scopedFamilies: ReadonlySet<ScopedFamily>;
+  /** Family → the design-system files that use its tokens. */
+  readonly familyFiles: ReadonlyMap<string, ReadonlySet<string>>;
+  /**
+   * `filesUsing` maps each token family to the design-system files that use it;
+   * a family that at most one of them uses is scoped. Without it, only sidebar
+   * and chart are.
+   */
+  constructor(tokens: Token[], options?: {
+    filesUsing?: ReadonlyMap<string, ReadonlySet<string>> | undefined;
+  });
+  has(category: TokenCategory): boolean;
+  byCssVar(name: string): Token | undefined;
+  /** The scoped family a token belongs to, if any. */
+  scopedFamilyOf(token: Token): ScopedFamily | undefined;
+  nearestColor(color: Oklch, limit?: number): Nearest<ColorCandidate>[];
+  /**
+   * The token to suggest for a color. Perceptual distance alone picks badly:
+   * several tokens share a value (`muted`, `accent`, `sidebar-accent`,
+   * `chart-2`...), and a pale yellow sits 0.07 from a light gray. So among the
+   * tokens close enough to swap in, of the same hue, it prefers the ones made
+   * for the role (`muted-foreground` for `text-gray-500`), and sidebar and
+   * chart tokens only in a sidebar or a chart.
+   */
+  suggestColor(color: Oklch, query?: ColorQuery): ColorSuggestion | undefined;
+  /** The step closest to the magnitude of `px`; callers keep the sign. */
+  nearestLength(category: 'spacing' | 'radius', px: number): NearestLength | undefined;
+  /**
+   * Tailwind v4 derives `p-<n>` from `--spacing` for any n. Whole and half
+   * steps (`p-13`, `p-4.5`) count as the scale, plus the static `p-px`;
+   * quarter steps are valid but off-grid, like the arbitrary values they replace.
+   */
+  private spacingSteps;
+  /** px value of a token-like length string, resolving `var()` against the token set. */
+  toPx(value: string): number | undefined;
+}
+//#endregion
+//#region src/lint/target.d.ts
+/** What the lint rules need to know about the design system. */
+declare class LintTarget {
+  readonly model: DesignSystemModel;
+  readonly config: Pick<ResolvedConfig, 'elements' | 'importPath'> & Partial<Pick<ResolvedConfig, 'designSystems'>>;
+  private readonly resolver?;
+  readonly components: Map<string, ComponentInfo>;
+  /** Every component under each name and alias, when two design systems share one (`Button`). */
+  private readonly named;
+  readonly tokens: TokenIndex;
+  /** Native element → the component that replaces it. */
+  readonly elements: Map<string, ComponentInfo>;
+  /** The `elements` entries the config sets explicitly. */
+  private readonly configured;
+  readonly componentFiles: Set<string>;
+  /** Every value the component files export, components or not (`Icons`, `buttonVariants`). */
+  readonly exports: Set<string>;
+  private readonly importPaths;
+  private readonly importPrefixes;
+  /** Component files relative to the root, without extension (`components/ui/button`). */
+  private readonly componentModules;
+  private readonly moduleDirs;
+  /** The files extraction read, when the model says. */
+  private readonly sources?;
+  /**
+   * `resolver` finds the module an import points at and what it exports
+   * (`@calcom/ui/components/icon` → `components/icon/index.ts`), so a name from
+   * a module the model left out is not taken for an invented one. Without it,
+   * every missing name is invented.
+   */
+  constructor(model: DesignSystemModel, config: Pick<ResolvedConfig, 'elements' | 'importPath'> & Partial<Pick<ResolvedConfig, 'designSystems'>>, resolver?: Pick<ModuleResolver, "locate" | "exportsOf"> | undefined);
+  /**
+   * Whether an import specifier points at the design system. Relative
+   * specifiers are resolved against `fromFile` (relative to the root) and
+   * must land on a component file, in a directory that holds one, or on that
+   * directory itself (a barrel: `../components/ui` and its index).
+   */
+  isDesignSystemImport(specifier: string, fromFile?: string): boolean;
+  /**
+   * Whether `name`, imported from the design system, may be a real export the
+   * model left out rather than an invented one: its module exists outside the
+   * folders extraction read and exports `name`, or re-exports from such a
+   * module (an excluded `icons/` folder, a barrel's `export * from "./icons"`).
+   * A module declared in a package's `exports` but not on disk counts too,
+   * except the design system's own import path.
+   */
+  outsideModel(specifier: string, name: string, fromFile?: string): boolean;
+  /**
+   * The component a JSX tag means when `name` is imported from `specifier`, among the
+   * model's components of that name: the one declared where the import leads, through
+   * barrels (`export { Button } from "./Button"`, `export *`). `undefined` when it leads to
+   * a declaration the model does not have (another package's `Button`, or a file of the
+   * same name outside the component folders), which is not ours to check. Where the import
+   * cannot be followed, the component of that name, as before.
+   */
+  componentFor(name: string, specifier: string, fromFile: string): ComponentInfo | undefined;
+  /**
+   * Where what `file` exports as `name` is declared, following re-exports: the file
+   * (relative to the root) and its name there, `{ namespace }` for a module namespace,
+   * `undefined` when it does not export it, `null` when a step of the way does not
+   * resolve or cannot be read.
+   */
+  private originOf;
+  private mayExport;
+  /**
+   * Whether `<Component>` can replace the native element `key` (`a`,
+   * `input[type=checkbox]`) by renaming the tag: the config maps it, it
+   * renders that element, or it takes the element's own attributes.
+   */
+  isDropIn(component: ComponentInfo, key: string): boolean;
+  /**
+   * Whether a component asks for nothing beyond what the element takes: no
+   * required prop of its own, and the element's own attributes (`htmlFor` for a
+   * label). Unknown when its props do not fully resolve, so false.
+   */
+  private plainFor;
+  /** The component a module exports as `default`, for `import Anything from "..."`. */
+  defaultExport(specifier: string, fromFile?: string): ComponentInfo | undefined;
+  private resolveRelative;
+  /** Component names for "did you mean" suggestions. */
+  names(): string[];
+}
+//#endregion
+//#region src/lint/context.d.ts
+interface Report {
+  start: number;
+  end: number;
+  message: string;
+  suggestion?: string | undefined;
+  fix?: TextEdit[] | undefined;
+  /** Rules may downgrade (never upgrade) their configured severity for low-confidence findings. */
+  severity?: Severity;
+}
+interface RuleContext {
+  file: string;
+  text: string;
+  sourceFile: ts.SourceFile;
+  target: LintTarget;
+  analysis: Analysis;
+  options: RuleOptions;
+  /** True when the checked file is one of the design system's own component sources. */
+  isDesignSystemSource: boolean;
+  resolve(element: JsxNode): Resolution;
+  report(report: Report): void;
+  /** Records a component the model does not include, which the rules cannot check. */
+  unchecked(name: string, module: string): void;
+}
+interface Rule {
+  id: RuleId;
+  description: string;
+  run(context: RuleContext): void;
+}
+type Resolution =
+/** A design-system component. */
+{
+  kind: 'component';
+  component: ComponentInfo;
+} |
+/** A lowercase JSX tag. */
+{
+  kind: 'intrinsic';
+  tag: string;
+} |
+/** Imported from the design system's path, but the design system has no such component. */
+{
+  kind: 'missing-export';
+  name: string;
+  source: string;
+} |
+/** `Card.Header` where `Card` is a design-system component without that member. */
+{
+  kind: 'missing-member';
+  owner: ComponentInfo;
+  member: string;
+} |
+/** Not imported, not declared and not a design-system component. */
+{
+  kind: 'unresolved';
+  name: string;
+} |
+/** Imported from elsewhere or declared locally: not our business. */
+{
+  kind: 'external';
+};
+//#endregion
+//#region src/lint/rules/index.d.ts
+/** Every rule, in the order they run. */
+export declare const RULES: readonly Rule[];
+//#endregion
+//#region src/lint/format.d.ts
+type OutputFormat = 'pretty' | 'json' | 'github' | 'sarif';
+/**
+ * Renders check results:
+ * - `pretty`: grouped by file, for terminals and agents,
+ * - `json`: the raw results,
+ * - `github`: workflow commands that GitHub Actions turns into PR annotations,
+ * - `sarif`: a SARIF 2.1.0 log, for GitHub code scanning and other SARIF consumers.
+ */
+export declare function formatDiagnostics(results: CheckResult[], format: OutputFormat, options?: {
+  color?: boolean;
+  /** Findings a baseline accepted; set when a baseline was applied. */
+  baselined?: number | undefined;
+  /** Says that baseline entries no longer occur, and how to drop them. */
+  fixedHint?: string | undefined;
+  /** What the run left out: `5 design-system files skipped`, `12 tests and stories left out`. */
+  notes?: readonly string[] | undefined;
+  /**
+   * `sarif` and `github`: a result's file as a path relative to the repository root, which
+   * code scanning and workflow commands resolve locations against.
+   */
+  uri?: ((file: string) => string) | undefined;
+}): string;
+//#endregion
+//#region src/lint/index.d.ts
+interface CheckOptions {
+  /** File name used in results and to pick TSX vs JSX parsing. Default `snippet.tsx`. */
+  filename?: string | undefined;
+  rules: Record<RuleId, ResolvedRule>;
+}
+/**
+ * Lints a TSX/JSX snippet or file against the design system. Purely
+ * syntactic: no type-checking of the snippet, so it works on fragments an
+ * agent has not saved yet.
+ */
+export declare function checkSource(code: string, target: LintTarget, options: CheckOptions): CheckResult;
+/** Applies non-overlapping fixes from the end of the file backwards. */
+export declare function applyFixes(code: string, diagnostics: Diagnostic[]): string;
+//#endregion
+//#region src/search/bm25.d.ts
+/**
+ * Okapi BM25 over weighted fields (BM25F-style: field weights scale term
+ * frequency and document length). Small, dependency-free and deterministic,
+ * which is what a local tool index of a few hundred documents needs.
+ */
+interface Bm25Options {
+  k1?: number;
+  b?: number;
+}
+interface Bm25Hit<T> {
+  item: T;
+  score: number;
+  /** Matched query terms, best first. */
+  terms: string[];
+}
+declare class Bm25Index<T> {
+  private readonly docs;
+  private readonly df;
+  private totalLength;
+  private readonly k1;
+  private readonly b;
+  constructor(options?: Bm25Options);
+  /** Adds a document as `[terms, weight]` fields. */
+  add(item: T, fields: [terms: string[], weight: number][]): void;
+  get size(): number;
+  search(query: Map<string, number>, limit?: number): Bm25Hit<T>[];
+}
+//#endregion
+//#region src/search/index.d.ts
+interface SearchHit {
+  component: ComponentInfo;
+  score: number;
+  matched: string[];
+}
+export declare function searchComponents(index: Bm25Index<ComponentInfo>, query: string, limit?: number): SearchHit[];
+//#endregion
+//#region src/util/log.d.ts
+/**
+ * Diagnostics go to stderr: in stdio mode stdout carries JSON-RPC and must
+ * never receive anything else.
+ */
+interface Logger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+//#endregion
+//#region src/design-system.d.ts
+/** A loaded design system: the model plus the indexes the tools query. */
+export declare class DesignSystem {
+  readonly model: DesignSystemModel;
+  readonly config: ResolvedConfig;
+  readonly lint: LintTarget;
+  private readonly searchIndex;
+  constructor(model: DesignSystemModel, config: ResolvedConfig);
+  get root(): string;
+  get components(): ComponentInfo[];
+  get tokens(): Token[];
+  get tokenIndex(): TokenIndex;
+  /** Top-level components, i.e. not parts of another component. */
+  roots(): ComponentInfo[];
+  /** Looks a component up by name, alias, `Card.Header`/`CardHeader` or case-insensitively. */
+  getComponent(name: string): ComponentInfo | undefined;
+  suggestComponent(name: string): string | undefined;
+  search(query: string, limit?: number): SearchHit[];
+  /** Tokens, core ones first: scoped families (`sidebar-*`, `chart-*`) follow the rest, which an agent should reach for. */
+  getTokens(filter?: {
+    category?: TokenCategory | undefined;
+    query?: string | undefined;
+  }): Token[];
+  /** Tokens a component's classes and CSS variables reference, e.g. `bg-primary` → `primary`. */
+  relatedTokens(component: ComponentInfo): Token[];
+  /**
+   * What the rules could not check, when it matters: without components the
+   * component rules find nothing, and without color tokens neither does
+   * no-hardcoded-color, so a clean result says little. Undefined when both exist.
+   * `where` names the projects it applies to, at a workspace root: `in apps/web`.
+   */
+  notice(where?: string): string | undefined;
+  check(code: string, filename?: string): CheckResult;
+}
+interface LoadOptions {
+  /** Use the on-disk extraction cache. Default true. */
+  cache?: boolean;
+  logger?: Logger;
+  /** Previous TypeScript program, reused for incremental rebuilds. */
+  oldProgram?: ts.Program | undefined;
+}
+interface BuildResult {
+  model: DesignSystemModel;
+  program?: ts.Program | undefined;
+  /** Fingerprint of every input file; unchanged fingerprint means nothing to rebuild. */
+  key?: string;
+  /** Project files the model depends on beyond the tracked ones; pass them to `fingerprint`. */
+  dependencies?: string[];
+}
+/**
+ * Fingerprint of the files a config tracks (paths, sizes, mtimes), plus the
+ * `dependencies` of a previous build, without extracting anything.
+ */
+export declare function fingerprint(config: ResolvedConfig, dependencies?: readonly string[]): Promise<string>;
+export declare function buildModel(config: ResolvedConfig, options?: LoadOptions): Promise<BuildResult>;
+export declare function loadDesignSystem(config: ResolvedConfig, options?: LoadOptions): Promise<DesignSystem>;
+/**
+ * Owns the current DesignSystem. Loads lazily, rebuilds when watched files
+ * change (reusing the previous TypeScript program), and never serves a
+ * half-built model: callers get the in-flight build when one is running.
+ */
+interface HostOptions extends LoadOptions {
+  /** Builds the model; replaceable in tests. Defaults to `buildModel`. */
+  build?: typeof buildModel;
+  /**
+   * Re-reads the config when its file changes while watching. Defaults to
+   * loading the same config file; pass your own to keep overrides such as CLI flags.
+   */
+  loadConfig?: () => Promise<ResolvedConfig>;
+}
+export declare class DesignSystemHost {
+  private config;
+  private readonly options;
+  private current?;
+  private program?;
+  private key?;
+  private dependencies;
+  /** Bumped by every build; only the latest may update the state above. */
+  private generation;
+  private configChanged;
+  private watchers;
+  /** Recursively watched directories, and the config files watched through their directory. */
+  private watchedRoots;
+  private readonly watchedDirs;
+  private readonly watchedFiles;
+  private timer?;
+  private readonly listeners;
+  constructor(config: ResolvedConfig, options?: HostOptions);
+  get(): Promise<DesignSystem>;
+  reload(): Promise<DesignSystem>;
+  onChange(listener: (ds: DesignSystem) => void): () => void;
+  /** Watches the component, token and docs locations, the config and the tsconfig chain. */
+  watch(): void;
+  /**
+   * Watches the config file, the tsconfig and the tsconfigs it extends through
+   * their directories: editors save by renaming a new file over the old one,
+   * which ends a watch on the file. Called again after each build, so a new
+   * `extends` target is picked up.
+   */
+  private watchConfigFiles;
+  private changed;
+  close(): void;
+  private watchDirectory;
+  private schedule;
+  /** Re-reads the config, re-watches what it points at and rebuilds. */
+  private reloadConfig;
+  private build;
+}
+//#endregion
+//#region src/extract/components.d.ts
+interface ExtractComponentsOptions {
+  root: string;
+  /** Absolute paths of the component source files. */
+  files: string[];
+  tsconfig?: string | undefined;
+  /** Package name the design system is imported from; overrides tsconfig path inference. */
+  importPath?: string | undefined;
+  /** Specifiers from the `exports` of the package that holds the components; checked before tsconfig paths. */
+  imports?: ImportMapping[] | undefined;
+  /** Previous program, to let TypeScript reuse unchanged source files when watching. */
+  oldProgram?: ts.Program | undefined;
+}
+interface ExtractComponentsResult {
+  components: ComponentInfo[];
+  propSets: Record<string, string[]>;
+  /** Every value the component files export, components or not (`Icons`, `buttonVariants`). */
+  exports: string[];
+  warnings: string[];
+  program: ts.Program;
+  /** Project files extraction depends on: the tsconfig chain and every module the components import. */
+  dependencies: string[];
+}
+/**
+ * Extracts React components from source with the TypeScript checker: props
+ * (types, required, defaults, JSDoc), `cva()`/`tv()` variants, the native
+ * element they wrap, and compound structure (`CardHeader` under `Card`,
+ * `Tabs.List` via static members or `Object.assign`).
+ */
+export declare function extractComponents(options: ExtractComponentsOptions): ExtractComponentsResult;
+//#endregion
+//#region src/extract/cva.d.ts
+/** A `cva()` (class-variance-authority) or `tv()` (tailwind-variants) definition. */
+interface VariantDefinition {
+  /** The variable it is assigned to, e.g. `buttonVariants`. */
+  name: string;
+  base: string;
+  variants: VariantInfo[];
+  compoundVariants: CompoundVariantInfo[];
+  node: ts.CallExpression;
+}
+/** Finds every `const x = cva(base, { variants, defaultVariants })` in a file. */
+export declare function findVariantDefinitions(sourceFile: ts.SourceFile): Map<string, VariantDefinition>;
+//#endregion
+//#region src/extract/docs.d.ts
+interface ParsedDoc {
+  file: string;
+  title?: string;
+  description?: string;
+  sections: DocSection[];
+  examples: ExampleInfo[];
+  frontmatter: Record<string, string | string[]>;
+}
+/**
+ * Parses a component's Markdown/MDX page into a description, sections and
+ * runnable examples. MDX `import`/`export` lines are dropped; JSX in prose is
+ * kept as text.
+ */
+export declare function parseDoc(text: string, file: string): ParsedDoc;
+/** Attaches docs and their examples to components. Returns warnings for unmatched pages. */
+export declare function attachDocs(components: ComponentInfo[], docs: ParsedDoc[]): string[];
+//#endregion
+//#region src/catalog.d.ts
+/** One project's design system at a workspace root. */
+interface ServedProject {
+  ds: DesignSystem;
+  /** Folder relative to the workspace root, with forward slashes. */
+  dir: string;
+  name?: string | undefined;
+}
+/**
+ * The projects of a workspace root, as the MCP server serves them: one design system per
+ * path, and all of them for the merged catalog.
+ */
+interface ProjectSet {
+  root: string;
+  /** Folders of the projects with a design system, relative to the root. */
+  dirs: string[];
+  /** The design system that checks `target`, a file or folder relative to the root. */
+  forPath(target: string): Promise<ServedProject>;
+  /** Every project with a design system, loaded. */
+  all(): Promise<ServedProject[]>;
+  /** Their components and tokens together, rebuilt when a project reloads. */
+  catalog(): Promise<Catalog>;
+}
+/** A component of the merged catalog: one source declaration, whichever projects use it. */
+interface CatalogEntry {
+  /** As the first project that has it describes it, with `source.file` relative to the workspace root. */
+  component: ComponentInfo;
+  /** The design system to render it with (its props, tokens and parts). */
+  ds: DesignSystem;
+  /** The package its source file belongs to: `@acme/ui`, or the app's own name. */
+  package: string;
+  /** Folders of the projects that use it. */
+  projects: string[];
+  /** Another component of the catalog has the same name. */
+  ambiguous: boolean;
+}
+interface CatalogToken {
+  token: Token;
+  ds: DesignSystem;
+  package: string;
+  projects: string[];
+}
+/**
+ * Every project's components and tokens in one list, for a workspace root when no path
+ * picks a project. A component used by several projects (a design-system package) is
+ * listed once, tagged with its package; two different components under one name are both
+ * listed, each with its package, and a lookup by that name returns both.
+ */
+declare class Catalog {
+  readonly root: string;
+  readonly projects: ServedProject[];
+  readonly entries: CatalogEntry[];
+  readonly tokens: CatalogToken[];
+  private readonly index;
+  constructor(root: string, projects: ServedProject[]);
+  /** Top-level components, not parts of another. */
+  roots(): CatalogEntry[];
+  /** Every distinct component a name resolves to, through each project's lookup. */
+  find(name: string): CatalogEntry[];
+  suggest(name: string): string | undefined;
+  search(query: string, limit?: number): (SearchHit & {
+    entry: CatalogEntry;
+  })[];
+  /** Tokens as `get_tokens` filters them, core ones before scoped families. */
+  getTokens(filter?: {
+    category?: TokenCategory | undefined;
+    query?: string | undefined;
+  }): CatalogToken[];
+}
+//#endregion
+//#region src/server/index.d.ts
+export declare const INSTRUCTIONS = "This server describes the project's design system: its React components (props, variants, parts), design tokens and usage docs, and lints UI code against it.\nWhen writing or changing UI in this project:\n1. Find components with search_components (by intent) or list_components.\n2. Read get_component before using a component: use only the props and variant values it lists.\n3. Style with tokens from get_tokens, never with hex/rgb colors, arbitrary px values or Tailwind's default palette.\n4. Run check_ui on every snippet or file you write and fix all errors before you finish.\nIn a monorepo served from its root, pass `path` (the file you are editing) to list_components, get_component, search_components and get_tokens, and `path` or `filename` to check_ui, so each answer comes from that file's own project.";
+interface CreateServerOptions {
+  /**
+   * Resolves the design system to serve. Called per request, so it can be swapped on reload.
+   * `target` is the `path` (or `filename`) the request names, if any, as given.
+   */
+  getDesignSystem: (target?: string) => Promise<DesignSystem>;
+  /**
+   * At a workspace root: its projects. When this resolves to a set, the tools take a `path`
+   * to pick a project and serve every project together without one, and `getDesignSystem`
+   * is not called. `target` is the `path` (or `filename`) the request names, if any.
+   */
+  getProjects?: (target?: string) => Promise<ProjectSet | undefined>;
+}
+/** Builds the MCP server: five tools, two resources and one prompt. Transport-agnostic. */
+export declare function createServer({ getDesignSystem, getProjects }: CreateServerOptions): McpServer;
+//#endregion
+//#region src/server/stdio.d.ts
+interface ServeOptions extends LoadConfigOptions {
+  cwd: string;
+  cache: boolean;
+  watch: boolean;
+  logger: Logger;
+  /** Defaults to stdio. */
+  transport?: Transport;
+}
+/** The running server: `close()` ends the connection and stops watching. */
+interface ServerHandle {
+  close(): Promise<void>;
+}
+/**
+ * Starts the server (on stdio unless another transport is given), for clients on
+ * either protocol era: a 2026-07-28 client (stateless, `server/discover`) and a
+ * 2025-era one (the `initialize` handshake) are both served, the era chosen by the
+ * client's first message.
+ *
+ * The project root comes from `--root` or `--config`, a config file in the working
+ * directory, or the working directory itself when it holds a project (a
+ * package.json, a components.json). MCP roots, which the 2026-07-28 revision
+ * deprecates, are the fallback for a 2025-era client that starts servers somewhere
+ * else (Claude Desktop starts them in `/`): its first `file://` root. At a monorepo
+ * root with no design system of its own, every project in it is served.
+ *
+ * When none of those gives a project (a client that starts servers in the home or the
+ * plugin's folder and reports no roots), each request's project is found from the
+ * absolute path it names (`findProjectRoot`): the nearest folder at or above it with a
+ * project marker, or the monorepo root above that, served as if the server had been
+ * started there, except that a config there is read only when it is JSON: a prompt can
+ * choose the path, so a JavaScript or TypeScript config is not run. Each root found is
+ * loaded once and kept; a request without an absolute path is answered from the one root
+ * found so far.
+ */
+export declare function serveStdio(options: ServeOptions): Promise<ServerHandle>;
+//#endregion
+//#region src/version.d.ts
+export declare const VERSION: string;
+//#endregion
+export { type CheckResult, type ComponentDocs, type ComponentInfo, type CompoundVariantInfo, type Config, type DesignSystemModel, type Diagnostic, type DocSection, type ExampleInfo, type HostOptions, type InheritedProps, type LoadConfigOptions, type LoadOptions, type OutputFormat, type PropInfo, RULE_IDS, type ResolvedConfig, type RuleId, type Severity, type SourceLocation, type TOKEN_CATEGORIES, type TextEdit, type Token, type TokenCategory, type VariantInfo, configJsonSchema, defineConfig, loadConfig };