4-01 · component-manifest：一份 JSON 管六处一致性

// component-manifest.json L2-12
{
  "name": "button",
  "docsGroup": "basic",
  "docsText": "Button 按钮",
  "installExports": ["XyButton", "XyButtonGroup"],
  "installChecks": [
    { "kind": "component", "name": "xy-button" },
    { "kind": "component", "name": "xy-button-group" }
  ],
  "styleImports": ["button"]
},

// component-manifest.json L375-431（feedback 组连续节选，缩进规整到顶层）
{
  "name": "message",
  "docsGroup": "feedback",
  "docsText": "Message 消息提示",
  "installExports": ["XyMessage"],
  "installChecks": [{ "kind": "globalProperty", "name": "$message" }],
  "styleImports": ["message"]
},
{
  "name": "notification",
  "docsGroup": "feedback",
  "docsText": "Notification 通知",
  "installExports": ["XyNotification", "XyNotificationService"],
  "installChecks": [
    { "kind": "component", "name": "xy-notification" },
    { "kind": "globalProperty", "name": "$notify" }
  ],
  "styleImports": ["notification"]
},
{
  "name": "backtop",
  "docsGroup": "feedback",
  "docsText": "Backtop 回到顶部",
  "installExports": ["XyBacktop"],
  "installChecks": [{ "kind": "component", "name": "xy-backtop" }],
  "styleImports": ["backtop"]
},
{
  "name": "collapse",
  "docsGroup": "feedback",
  "docsText": "Collapse 折叠面板",
  "installExports": ["XyCollapse", "XyCollapseItem"],
  "installChecks": [
    { "kind": "component", "name": "xy-collapse" },
    { "kind": "component", "name": "xy-collapse-item" }
  ],
  "styleImports": ["collapse"]
},
{
  "name": "empty",
  "docsGroup": "feedback",
  "docsText": "Empty 空状态",
  "installExports": ["XyEmpty"],
  "installChecks": [{ "kind": "component", "name": "xy-empty" }],
  "styleImports": ["empty"]
},
{
  "name": "loading",
  "docsGroup": "feedback",
  "docsText": "Loading 加载",
  "installExports": ["XyLoading"],
  "installChecks": [
    { "kind": "directive", "name": "loading" },
    { "kind": "globalProperty", "name": "$loading" }
  ],
  "styleImports": ["loading"]
},

// component-manifest.json L566-573
{
  "name": "scheduler",
  "docsGroup": "data",
  "docsText": "Scheduler 排期日历",
  "installExports": ["XyScheduler"],
  "installChecks": [{ "kind": "component", "name": "xy-scheduler" }],
  "styleImports": ["scheduler"]
},

// component-manifest.json L619-627
{
  "name": "editor",
  "docsGroup": "form",
  "docsText": "Editor 编辑器",
  "installExports": ["XyEditor"],
  "installChecks": [{ "kind": "component", "name": "xy-editor" }],
  "styleImports": ["editor"]
},

// component-manifest.json L212-219（styleImports 空数组示例）
{
  "name": "config-provider",
  "docsGroup": "form",
  "docsText": "Config Provider 全局配置",
  "installExports": ["XyConfigProvider"],
  "installChecks": [{ "kind": "component", "name": "xy-config-provider" }],
  "styleImports": []
},

// component-manifest.json L527-534（复用他组件样式示例）
{
  "name": "countdown",
  "docsGroup": "data",
  "docsText": "Countdown 倒计时",
  "installExports": ["XyCountdown"],
  "installChecks": [{ "kind": "component", "name": "xy-countdown" }],
  "styleImports": []
},

// packages/components/component-manifest.ts L1-40
import manifestJson from "./component-manifest.json" with { type: "json" };

export type ComponentDocsGroup = "basic" | "form" | "feedback" | "data";

interface RawComponentInstallCheck {
  kind: "component" | "directive" | "globalProperty";
  name: string;
}

interface RawComponentManifestEntry {
  name: string;
  docsGroup: ComponentDocsGroup;
  docsText: string;
  installExports: string[];
  installChecks: RawComponentInstallCheck[];
  styleImports: string[];
}

export interface ComponentManifestEntry {
  name: string;
  docsGroup: ComponentDocsGroup;
  docsText: string;
  installExports: string[];
  installChecks: RawComponentInstallCheck[];
  install: {
    components: string[];
    directives: string[];
    globals: string[];
  };
  styleImports: string[];
}

const rawManifest = manifestJson as RawComponentManifestEntry[];

const docsGroupTextMap: Record<ComponentDocsGroup, string> = {
  basic: "基础组件",
  form: "表单与录入",
  feedback: "反馈与浮层",
  data: "数据展示"
};

// packages/components/component-manifest.ts L42-81
const docsGroupOrder: ComponentDocsGroup[] = ["basic", "form", "feedback", "data"];

export const componentManifest = rawManifest.map((entry) => ({
  ...entry,
  install: {
    components: entry.installChecks
      .filter((check) => check.kind === "component")
      .map((check) => check.name),
    directives: entry.installChecks
      .filter((check) => check.kind === "directive")
      .map((check) => check.name),
    globals: entry.installChecks
      .filter((check) => check.kind === "globalProperty")
      .map((check) => check.name)
  }
})) satisfies ComponentManifestEntry[];

export const publicComponentNames = componentManifest.map((entry) => entry.name);

export const installableComponentExportNames = componentManifest.flatMap(
  (entry) => entry.installExports
);

export const installCheckEntries = componentManifest.flatMap((entry) => entry.installChecks);

export const themeStyleImportNames = Array.from(
  new Set(componentManifest.flatMap((entry) => entry.styleImports))
);

export const componentStyleImports = themeStyleImportNames;

export const componentDocsSidebarGroups = docsGroupOrder.map((group) => ({
  text: docsGroupTextMap[group],
  items: componentManifest
    .filter((entry) => entry.docsGroup === group)
    .map((entry) => ({
      text: entry.docsText,
      link: `/components/${entry.name}`
    }))
}));

// packages/components/index.ts L1-54
import type { App, Plugin } from "vue";
import "./style.css";
import * as XiaoyeComponentExports from "./exports";
import { installableComponentExportNames } from "./component-manifest";

export type { ComponentSize, ComponentStatus, SelectOption } from "xiaoye-primitives";
export * from "./exports";

const INSTALL_KEY = Symbol.for("xiaoye-components:installed");

function isInstallableExport(value: unknown): value is Plugin {
  return (
    (typeof value === "function" || typeof value === "object") &&
    value !== null &&
    "install" in value &&
    typeof (value as { install?: unknown }).install === "function"
  );
}

const installableExports = Array.from(
  new Set(
    installableComponentExportNames
      .map((name) => XiaoyeComponentExports[name as keyof typeof XiaoyeComponentExports])
      .filter(isInstallableExport)
  )
) as Plugin[];

export function install(app: App) {
  const appWithInstallFlag = app as App & {
    [INSTALL_KEY]?: boolean;
  };

  if (appWithInstallFlag[INSTALL_KEY]) {
    return;
  }

  appWithInstallFlag[INSTALL_KEY] = true;

  installableExports.forEach((component) => {
    app.use(component);
  });
}

declare module "vue" {
  interface ComponentCustomProperties {
    $loading?: typeof import("./loading").XyLoadingService;
    $message?: typeof import("./message").XyMessage;
    $notify?: typeof import("./notification").XyNotificationService;
  }
}

export default {
  install
};

/* packages/components/style.css L1 */
@import "../theme/index.css";

/* packages/theme/index.css L1-9（全文共 73 行，L10-73 为其余 64 行组件 @import） */
@import "@xiaoye/primitives/style.css";
@import "./src/components/button.css";
@import "./src/components/link.css";
@import "./src/components/breadcrumb.css";
@import "./src/components/text.css";
@import "./src/components/badge.css";
@import "./src/components/icon.css";
@import "./src/components/avatar.css";
@import "./src/components/avatar-group.css";

// scripts/check-components.mjs L1-55
import fs from "node:fs";
import path from "node:path";

const repoRoot = process.cwd();
const manifestPath = path.join(repoRoot, "packages/components/component-manifest.json");
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));

const componentNames = manifest.map((entry) => entry.name);
const styleNames = manifest.flatMap((entry) => entry.styleImports);

function readFile(relativePath) {
  return fs.readFileSync(path.join(repoRoot, relativePath), "utf8");
}

function listBasenames(relativeDir, extension) {
  return fs
    .readdirSync(path.join(repoRoot, relativeDir))
    .filter((file) => file.endsWith(extension))
    .map((file) => file.slice(0, -extension.length))
    .sort();
}

function listComponentTestGroups() {
  const componentsDir = path.join(repoRoot, "packages/components");
  return fs
    .readdirSync(componentsDir, { withFileTypes: true })
    .filter((entry) => entry.isDirectory())
    .map((entry) => entry.name)
    .filter((name) =>
      fs.existsSync(path.join(componentsDir, name, "__tests__")) &&
      fs
        .readdirSync(path.join(componentsDir, name, "__tests__"))
        .some((file) => file.endsWith(".spec.ts"))
    )
    .sort();
}

function collectByRegex(source, regex, groupIndex = 1) {
  return [...source.matchAll(regex)].map((match) => match[groupIndex]).sort();
}

function diff(expected, actual) {
  const actualSet = new Set(actual);
  return expected.filter((item) => !actualSet.has(item));
}

function fail(message, values) {
  console.error(message);
  if (values.length > 0) {
    values.forEach((value) => {
      console.error(`- ${value}`);
    });
  }
  process.exitCode = 1;
}

// scripts/check-components.mjs L57-81
const componentDirs = fs
  .readdirSync(path.join(repoRoot, "packages/components"), { withFileTypes: true })
  .filter((entry) => entry.isDirectory() && entry.name !== "node_modules")
  .map((entry) => entry.name)
  .filter((name) => !["dist", "shared", "src"].includes(name))
  .sort();

const exportedComponentNames = collectByRegex(
  readFile("packages/components/exports.ts"),
  /export \* from "\.\/([^"]+)";/g
).filter((name) => name !== "shared");

const docComponentNames = listBasenames("apps/docs/components", ".md").filter(
  (name) => name !== "overview"
);

const typeFixtureNames = listBasenames("tests/types/fixtures", ".ts").filter((name) =>
  componentNames.includes(name)
);
const unitTestNames = listComponentTestGroups();

const themeImportNames = collectByRegex(
  readFile("packages/theme/index.css"),
  /@import "\.\/src\/components\/([^.]+)\.css";/g
);

// scripts/check-components.mjs L83-134
const mismatches = [
  {
    message: "组件目录与 manifest 不一致：",
    values: [
      ...diff(componentNames, componentDirs),
      ...diff(componentDirs, componentNames).map((name) => `${name} (多余目录)`)
    ]
  },
  {
    message: "导出入口与 manifest 不一致：",
    values: [
      ...diff(componentNames, exportedComponentNames),
      ...diff(exportedComponentNames, componentNames).map((name) => `${name} (多余导出)`)
    ]
  },
  {
    message: "组件文档与 manifest 不一致：",
    values: [
      ...diff(componentNames, docComponentNames),
      ...diff(docComponentNames, componentNames).map((name) => `${name} (多余文档)`)
    ]
  },
  {
    message: "类型夹具与 manifest 不一致：",
    values: [
      ...diff(componentNames, typeFixtureNames),
      ...diff(typeFixtureNames, componentNames).map((name) => `${name} (多余夹具)`)
    ]
  },
  {
    message: "组件单测与 manifest 不一致：",
    values: [
      ...diff(componentNames, unitTestNames),
      ...diff(unitTestNames, componentNames).map((name) => `${name} (多余单测目录)`)
    ]
  },
  {
    message: "样式入口与 manifest 不一致：",
    values: [
      ...diff(styleNames, themeImportNames),
      ...diff(themeImportNames, styleNames).map((name) => `${name} (多余样式导入)`)
    ]
  }
];

mismatches
  .filter((entry) => entry.values.length > 0)
  .forEach((entry) => fail(entry.message, entry.values));

if (process.exitCode !== 1) {
  console.log(`组件一致性校验通过，共校验 ${componentNames.length} 个公开组件。`);
}

组件文档与 manifest 不一致：
- foo
样式入口与 manifest 不一致：
- foo (多余样式导入)

// package.json L11
"check:components": "node scripts/check-components.mjs",

// package.json L16
"lint": "pnpm check:tokens && pnpm check:llms && pnpm check:components && pnpm check:pro-components && eslint .",

# .github/workflows/ci.yml L20-26（job 主 steps 节选）
      - run: pnpm install --frozen-lockfile
      - run: pnpm check:components
      - run: pnpm lint
      - run: pnpm typecheck
      # CI runner 内存有限，文件级并行曾致 OOM flaky（同一提交在 Release job 中全部通过）
      - run: pnpm test -- --no-file-parallelism
      - run: pnpm build

// packages/pro-components/__tests__/install.spec.ts L1-35
import { createApp, defineComponent, h } from "vue";
import { describe, expect, it, vi } from "vitest";
import XiaoyeProComponents from "../index";
import { proInstallCheckEntries } from "../component-manifest";

describe("XiaoyeProComponents", () => {
  it("重复 install 到同一个 app 时保持幂等", () => {
    const app = createApp(
      defineComponent({
        render() {
          return h("div");
        }
      })
    );

    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});

    XiaoyeProComponents.install(app);
    XiaoyeProComponents.install(app);

    proInstallCheckEntries.forEach((entry) => {
      if (entry.kind === "component") {
        expect(app.component(entry.name)).toBeTruthy();
      }
    });

    expect(
      warnSpy.mock.calls.some((args) =>
        String(args[0]).includes("already been registered in target app")
      )
    ).toBe(false);

    warnSpy.mockRestore();
  });
});

// element-plus dev 分支 packages/element-plus/make-installer.ts（22 行全文）
import { provideGlobalConfig } from '@element-plus/components/config-provider'
import { INSTALLED_KEY } from '@element-plus/constants'
import { version } from './version'

import type { App, Plugin } from 'vue'
import type { ConfigProviderContext } from '@element-plus/components/config-provider'

export const makeInstaller = (components: Plugin[] = []) => {
  const install = (app: App, options?: ConfigProviderContext) => {
    if (app[INSTALLED_KEY]) return

    app[INSTALLED_KEY] = true
    components.forEach((c) => app.use(c))

    if (options) provideGlobalConfig(options, app, true)
  }

  return {
    version,
    install,
  }
}

// element-plus dev 分支 packages/element-plus/component.ts 尾部（L222-229）
  ElTourStep,
  ElAnchor,
  ElAnchorLink,
  ElSegmented,
  ElMention,
  ElSplitter,
  ElSplitterPanel,
] as Plugin[]