onsystem 0.0.0-stage → 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,1132 @@
+import * as z from "zod";
+import ts from "typescript";
+import { Oklch } from "culori";
+import { McpServer, Transport } from "@modelcontextprotocol/server";
+//#region src/detect.d.ts
+/**
+ * How apps import a design-system module, from a package's `exports`:
+ * `@midday/ui/button` → `../../packages/ui/src/components/button.tsx`, or a
+ * pattern (`@workspace/ui/components/*` → `…/src/components/*.tsx`). A
+ * specifier without `*` and a pattern target map every matching file to one
+ * module: a package that exports its components from a barrel.
+ */
+interface ImportMapping {
+  specifier: string;
+  /** File or pattern relative to the root, with forward slashes. */
+  target: string;
+}
+/** One of several design systems an app uses, and how often its code imports it. */
+interface DesignSystemSource {
+  source: string;
+  components: string[];
+  imports: number;
+}
+//#endregion
+//#region src/config.d.ts
+export declare const RULE_IDS: readonly ["no-hardcoded-color", "no-hardcoded-spacing", "no-hardcoded-radius", "prefer-design-system-component", "no-unknown-component", "no-unknown-prop", "no-unknown-variant", "icon-button-accessible-name"];
+type RuleId = (typeof RULE_IDS)[number];
+declare const severitySchema: z.ZodEnum<{
+  off: "off";
+  warn: "warn";
+  error: "error";
+}>;
+type RuleSeverity = z.infer<typeof severitySchema>;
+declare const ruleOptionsSchema: z.ZodObject<{
+  allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+type RuleOptions = z.infer<typeof ruleOptionsSchema>;
+declare const configSchema: z.ZodObject<{
+  $schema: z.ZodOptional<z.ZodString>;
+  components: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+  exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  tokens: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    path: z.ZodString;
+    prefix: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    path: z.ZodString;
+    prefix: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>]>>]>>;
+  docs: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+  tsconfig: z.ZodOptional<z.ZodString>;
+  importPath: z.ZodOptional<z.ZodString>;
+  elements: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  includeDesignSystem: z.ZodOptional<z.ZodBoolean>;
+  rules: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+    "no-hardcoded-color": "no-hardcoded-color";
+    "no-hardcoded-spacing": "no-hardcoded-spacing";
+    "no-hardcoded-radius": "no-hardcoded-radius";
+    "prefer-design-system-component": "prefer-design-system-component";
+    "no-unknown-component": "no-unknown-component";
+    "no-unknown-prop": "no-unknown-prop";
+    "no-unknown-variant": "no-unknown-variant";
+    "icon-button-accessible-name": "icon-button-accessible-name";
+  }> & z.core.$partial, z.ZodUnion<readonly [z.ZodEnum<{
+    off: "off";
+    warn: "warn";
+    error: "error";
+  }>, z.ZodTuple<[z.ZodEnum<{
+    off: "off";
+    warn: "warn";
+    error: "error";
+  }>], null>, z.ZodTuple<[z.ZodEnum<{
+    off: "off";
+    warn: "warn";
+    error: "error";
+  }>, z.ZodObject<{
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>], null>]>>>;
+  overrides: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    files: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    rules: z.ZodRecord<z.ZodEnum<{
+      "no-hardcoded-color": "no-hardcoded-color";
+      "no-hardcoded-spacing": "no-hardcoded-spacing";
+      "no-hardcoded-radius": "no-hardcoded-radius";
+      "prefer-design-system-component": "prefer-design-system-component";
+      "no-unknown-component": "no-unknown-component";
+      "no-unknown-prop": "no-unknown-prop";
+      "no-unknown-variant": "no-unknown-variant";
+      "icon-button-accessible-name": "icon-button-accessible-name";
+    }> & z.core.$partial, z.ZodUnion<readonly [z.ZodEnum<{
+      off: "off";
+      warn: "warn";
+      error: "error";
+    }>, z.ZodTuple<[z.ZodEnum<{
+      off: "off";
+      warn: "warn";
+      error: "error";
+    }>], null>, z.ZodTuple<[z.ZodEnum<{
+      off: "off";
+      warn: "warn";
+      error: "error";
+    }>, z.ZodObject<{
+      allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>], null>]>>;
+  }, z.core.$strict>>>;
+}, z.core.$strict>;
+type Config = z.input<typeof configSchema>;
+/** Identity helper for typed `onsystem.config.ts` files. */
+export declare function defineConfig(config: Config): Config;
+interface TokenSourceConfig {
+  path: string;
+  prefix?: string | undefined;
+}
+interface ResolvedRule {
+  severity: RuleSeverity;
+  options: RuleOptions;
+}
+/** Rule settings for the files that match `files` (root-relative globs). */
+interface ResolvedOverride {
+  files: string[];
+  rules: Partial<Record<RuleId, ResolvedRule>>;
+}
+interface ResolvedConfig {
+  root: string;
+  configFile?: string | undefined;
+  components: string[];
+  exclude: string[];
+  tokens: TokenSourceConfig[];
+  docs: string[];
+  tsconfig?: string | undefined;
+  importPath?: string | undefined;
+  /** Import specifiers for component files, from the `exports` of the package that holds them. */
+  imports?: ImportMapping[] | undefined;
+  /** How the design system was found when the config does not say (`components.json`, a workspace package). */
+  detected?: string | undefined;
+  /**
+   * Several design systems found at once, the most imported first: its components win
+   * where two share a name, and are the ones suggested for native elements.
+   */
+  designSystems?: DesignSystemSource[] | undefined;
+  /** A Tailwind v3 config, which maps color classes to custom properties (`primary` → `hsl(var(--primary))`). */
+  tailwindConfig?: string | undefined;
+  elements: Record<string, string>;
+  /** `check` lints the component files themselves, which it skips by default. */
+  includeDesignSystem: boolean;
+  rules: Record<RuleId, ResolvedRule>;
+  /** Per-file rule settings, applied in order over `rules`. */
+  overrides?: ResolvedOverride[] | undefined;
+  /**
+   * The folder `overrides` globs are relative to, when it is not the root: the workspace
+   * root, for a project that takes its settings from a config there.
+   */
+  base?: string | undefined;
+  /** `components` comes from the config file or `--components`, not from detection or the defaults. */
+  configured?: boolean | undefined;
+  /**
+   * What to tell the user about the config's name: a config file found under its name from
+   * before the rename to onsystem. The CLI prints these once per run, the server logs them once.
+   */
+  deprecations?: string[] | undefined;
+}
+interface LoadConfigOptions {
+  /** Where to look for a config file when `root` and `config` are not given. */
+  cwd?: string;
+  /** Project root. Defaults to the config file's directory, then `cwd`. */
+  root?: string | undefined;
+  /** Explicit config file path. */
+  config?: string | undefined;
+  /**
+   * The folder the config file's paths and globs are written relative to, when it is not
+   * the root: a workspace root whose config a project in it takes on.
+   */
+  base?: string | undefined;
+  /** CLI overrides; replace the config file's values when set. */
+  components?: string[] | undefined;
+  tokens?: string[] | undefined;
+  docs?: string[] | undefined;
+  includeDesignSystem?: boolean | undefined;
+}
+export declare function loadConfig(options?: LoadConfigOptions): Promise<ResolvedConfig>;
+/** JSON Schema for editor completion in `onsystem.config.json`. */
+export declare function configJsonSchema(): Record<string, unknown>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * The design-system model the server exposes. Everything here is plain JSON so
+ * it can be cached on disk and returned as MCP structured content.
+ */
+declare const TOKEN_CATEGORIES: readonly ["color", "spacing", "radius", "typography", "shadow", "other"];
+type TokenCategory = (typeof TOKEN_CATEGORIES)[number];
+interface SourceLocation {
+  /** Path relative to the project root, with forward slashes. */
+  file: string;
+  /** 1-based line. */
+  line: number;
+}
+interface Token {
+  /**
+   * Canonical name: the DTCG path for JSON tokens (`color.brand.500`) or the
+   * custom property without its dashes for CSS tokens (`primary`, `radius-md`).
+   */
+  name: string;
+  category: TokenCategory;
+  /** The value with aliases resolved, as authored (`oklch(0.205 0 0)`, `0.5rem`). */
+  value: string;
+  /** Values for other modes or themes, e.g. `{ dark: "oklch(0.922 0 0)" }`. */
+  modes?: Record<string, string>;
+  /** The custom property to reference from CSS, e.g. `--primary`. */
+  cssVar?: string;
+  /**
+   * Tailwind theme key when the token is exposed through `@theme`
+   * (`primary` for `--color-primary`, `md` for `--radius-md`).
+   */
+  tailwind?: string;
+  /** Ready-to-paste usages, most idiomatic first: `bg-primary`, `var(--primary)`. */
+  usage: string[];
+  description?: string;
+  deprecated?: string | true;
+  /** Name of the token this one aliases, if any. */
+  aliasOf?: string;
+  /** Where the value comes from. `tailwind-default` marks Tailwind built-ins such as `--spacing`. */
+  origin?: 'tailwind-default';
+  source: SourceLocation;
+}
+interface PropInfo {
+  name: string;
+  /** TypeScript type as written by the checker, without `| undefined`. */
+  type: string;
+  required: boolean;
+  default?: string;
+  description?: string;
+  /** Allowed values when the type is a finite set of literals. */
+  values?: string[];
+  deprecated?: string | true;
+  /** `variant` when the prop comes from a `cva()` definition. */
+  kind: 'prop' | 'variant';
+}
+interface VariantInfo {
+  /** Variant prop name, e.g. `variant` or `size`. */
+  name: string;
+  values: string[];
+  default?: string;
+  /** Classes applied for each value, straight from the `cva()` config. */
+  classes: Record<string, string>;
+}
+interface CompoundVariantInfo {
+  when: Record<string, string | string[]>;
+  classes: string;
+}
+interface InheritedProps {
+  /** Source text of the type the props come from, e.g. `React.ComponentProps<"button">`. */
+  from: string;
+  count: number;
+  /** Key into `DesignSystemModel.propSets` with the full list of names. */
+  set: string;
+  /** Names in the set marked `@deprecated` (React Aria's `onClick`), left out of summaries. */
+  deprecated?: string[];
+}
+interface ExampleInfo {
+  title?: string;
+  code: string;
+  lang: string;
+  source: 'docs' | 'jsdoc';
+}
+interface DocSection {
+  heading: string;
+  body: string;
+}
+interface ComponentDocs {
+  file: string;
+  description?: string;
+  sections: DocSection[];
+  frontmatter: Record<string, string | string[]>;
+}
+interface ComponentInfo {
+  /** How the component is referenced in JSX: `Button`, `CardHeader` or `Tabs.List`. */
+  name: string;
+  /** Other names that resolve to the same component (e.g. `Card.Header` when `CardHeader` is also exported). */
+  aliases: string[];
+  description?: string;
+  deprecated?: string | true;
+  /** Suggested import specifier, e.g. `@/components/ui/button`. */
+  importPath: string;
+  /** Exported binding name, or the static member path for compound members. */
+  exportName: string;
+  source: SourceLocation;
+  /** The root component this one belongs to (`Card` for `CardHeader`). */
+  parent?: string;
+  /** Direct sub-components, in declaration order. */
+  subcomponents: string[];
+  /** Native element it renders or wraps, when it can be inferred (`button`, `input`). */
+  element?: string;
+  props: PropInfo[];
+  inherits: InheritedProps[];
+  /**
+   * True when part of the props type could not be resolved (missing
+   * `node_modules`, a type error). The linter then skips unknown-prop checks.
+   */
+  openProps: boolean;
+  variants: VariantInfo[];
+  compoundVariants: CompoundVariantInfo[];
+  examples: ExampleInfo[];
+  docs?: ComponentDocs;
+  /** Utility classes used in the component source; mapped to tokens at query time. */
+  classNames: string[];
+  /** CSS custom properties referenced in the component source. */
+  cssVars: string[];
+}
+interface DesignSystemModel {
+  version: 1;
+  root: string;
+  components: ComponentInfo[];
+  tokens: Token[];
+  /** Shared inherited prop-name lists, deduplicated across components. */
+  propSets: Record<string, string[]>;
+  /**
+   * Every value the component files export, components or not (`Icons`,
+   * `buttonVariants`), so the linter tells an invented name from a real export.
+   */
+  exports: string[];
+  /** Non-fatal problems found while extracting (unparseable files, unmatched docs). */
+  warnings: string[];
+  /**
+   * The component files extraction read, relative to the root: a name one of them exports
+   * that is not a component was seen, while a file outside them was never looked at.
+   */
+  sources?: string[];
+  stats: {
+    files: {
+      components: number;
+      tokens: number;
+      docs: number;
+    };
+    durationMs: number;
+    fromCache: boolean;
+  };
+}
+type Severity = 'error' | 'warning';
+interface TextEdit {
+  /** 0-based offsets into the checked source, end exclusive. */
+  range: [number, number];
+  text: string;
+}
+interface Diagnostic {
+  ruleId: string;
+  severity: Severity;
+  message: string;
+  /** 1-based. */
+  line: number;
+  /** 1-based. */
+  column: number;
+  endLine: number;
+  endColumn: number;
+  /** The offending source text. */
+  source: string;
+  /** What to write instead, e.g. `bg-destructive` or `<Button>`. */
+  suggestion?: string;
+  /** Edits that apply the suggestion, when it can be done mechanically. */
+  fix?: TextEdit[];
+}
+interface CheckResult {
+  file: string;
+  diagnostics: Diagnostic[];
+  errorCount: number;
+  warningCount: number;
+  /** With a baseline: findings it accepted, left out of `diagnostics` and the counts. */
+  baselined?: number;
+  /**
+   * Components imported from design-system modules the model does not include
+   * (extraction is incomplete), which the rules could not check.
+   */
+  unchecked?: {
+    names: string[];
+    modules: string[];
+  };
+  /**
+   * Why the file was not checked: it renders outside the browser's CSS (an
+   * Open Graph image through next/og, an email through React Email), where
+   * design tokens and classes do not apply.
+   */
+  skipped?: string;
+}
+//#endregion
+//#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/format.d.ts
+type OutputFormat = 'pretty' | 'json' | 'github';
+/**
+ * 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.
+ */
+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;
+}): string;
+//#endregion
+//#region src/lint/index.d.ts
+export declare const RULES: readonly Rule[];
+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. */
+  getDesignSystem: () => 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.
+   */
+  getProjects?: () => 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.
+ */
+export declare function serveStdio(options: ServeOptions): Promise<ServerHandle>;
+//#endregion
+//#region src/version.d.ts
+export declare const VERSION: string;
+//#endregion
+export type { CheckResult, ComponentDocs, ComponentInfo, CompoundVariantInfo, Config, DesignSystemModel, Diagnostic, DocSection, ExampleInfo, HostOptions, InheritedProps, LoadConfigOptions, LoadOptions, OutputFormat, PropInfo, ResolvedConfig, RuleId, Severity, SourceLocation, TOKEN_CATEGORIES, TextEdit, Token, TokenCategory, VariantInfo };