@oiyo/core 0.0.4 → 0.1.0

package/dist/index.d.cts

@@ -1,29 +1,16 @@
 /**
- * @oiyo/core v0.0.4
+ * @oiyo/core v0.1.0
  * Copyright (c) 2026 skiyee. All rights reserved.
  * Commercial software. See LICENSE for terms.
- * Official site: https://oiyo.pages.dev
+ * Official site: https://oiyo.js.org
  */
-import { n as PageFile, r as ResolvedPageMeta } from "./types-CO6ioKnp.cjs";
-import { OiyoConfig, PagesConfig } from "@oiyo/config";
+import { GlobRule, GlobalStyle, OiyoConfig, Page, PagesConfig, PagesJson } from "@oiyo/config";
+import * as _$vue from "vue";
 import * as _$magic_string0 from "magic-string";
-import { ConfigWatcher } from "c12";
 import { SFCDescriptor } from "@vue/compiler-sfc";
+import { ConfigWatcher } from "c12";
 import { Plugin } from "vite";
 
-//#region src/layout/types.d.ts
-/**
- * 布局信息
- */
-interface LayoutFile {
-  /** 布局应用名称 */
-  useName: string;
-  /** 布局组件名称 */
-  componentName: string;
-  /** 布局文件的绝对路径 */
-  filePath: string;
-}
-//#endregion
 //#region src/logger.d.ts
 type LogType = 'error' | 'warn' | 'info' | 'debug';
 type LogLevel = 'silent' | LogType | 'verbose';
@@ -56,19 +43,268 @@ interface LoggerOptions {
 }
 declare function createLogger(level?: LogLevel, options?: LoggerOptions): Logger;
 //#endregion
-//#region src/layout/index.d.ts
-declare class OiyoLayout {
+//#region src/modules/auto-api/types.d.ts
+/** 自动 API 条目，描述一个可被自动导入的模块导出项 */
+interface AutoApiItem {
+  /** 导出名称，如 'default' 或具名导出 */
+  exportName: string;
+  /** 源文件在磁盘上的绝对路径 */
+  filePath: string;
+  /** 对外暴露的导入路径（可能经过 importBase 规范化） */
+  importPath?: string;
+  /** 在消费端使用的本地标识符名称 */
+  name: string;
+}
+/** 手动注册的 API 条目，由用户在配置中通过 scan.apis.only 显式声明 */
+interface IncludedApi {
+  /** 源导出名称，默认与 name 相同 */
+  export?: string;
+  /** 模块来源路径 */
+  from: string;
+  /** 本地注册名称 */
+  name: string;
+}
+/** 批量扫描 API 的源配置，描述一个目录/包的扫描规则 */
+interface IncludedApisSource {
+  /** 需要排除的导出名称列表 */
+  exclude?: string[];
+  /** 忽略文件/目录的 glob 规则 */
+  ignore?: GlobRule;
+  /** 包导入基准路径（bare specifier），用于生成对外导入语句 */
+  importBase?: string;
+  /** 匹配文件的 glob 规则，默认匹配 TS/JS 模块文件 */
+  pattern?: GlobRule;
+  /** 扫描源目录/包的绝对路径 */
+  path: string;
+  /** 是否同时扫描并注册类型导出 */
+  types?: boolean;
+}
+//#endregion
+//#region src/state/index.d.ts
+declare class OiyoState {
+  private readonly config;
+  constructor(config: OiyoConfig);
+  get stateDir(): string;
+  get typesDir(): string;
+  get srcDir(): string;
+  get declarationEntryPath(): string;
+  get appTsconfigPath(): string;
+  get nodeTsconfigPath(): string;
+  private relativeToState;
+  private stringifyJson;
+  generateDeclarationEntry(): string;
+  generateAppTsconfig(): string;
+  generateNodeTsconfig(): string;
+  writeAppTsconfig(): string;
+  writeNodeTsconfig(): string;
+  writeDeclarationEntry(): string;
+  ensureDeclarationEntry(): string;
+}
+//#endregion
+//#region src/modules/auto-api/index.d.ts
+/**
+ * 自动 API 管理模块
+ *
+ * 负责扫描指定目录/包中的模块导出，生成自动导入语句和全局类型声明。
+ * 核心流程：
+ * 1. 构造时注册配置中的扫描器（registerConfigScanners）
+ * 2. collectApis() 扫描所有源文件并收集导出项
+ * 3. resolveImports() 分析代码引用并生成 import 语句
+ * 4. generateDeclaration() / writeDeclaration() 生成并写入全局类型声明文件
+ */
+declare class OiyoModAutoApi {
+  private readonly _config;
+  /** 已扫描收集的值导出列表 */
+  autoApis: AutoApiItem[];
+  /** 已扫描收集的类型导出列表 */
+  autoApiTypes: AutoApiItem[];
+  /** 值导出注册表，按 name 索引，用于去重和快速查找 */
+  private readonly autoApiMap;
+  /** 类型导出注册表，按 name 索引 */
+  private readonly autoApiTypeMap;
+  /** 手动注册的值 API（来自配置中的 only 声明） */
+  private readonly includedApis;
+  /** 手动注册的类型 API */
+  private readonly includedApiTypes;
+  /** 待扫描的 API 源列表 */
+  private readonly apiSources;
+  private readonly logger;
+  private readonly oiyoState;
+  constructor(_config: OiyoConfig, deps: {
+    logger: Logger;
+    oiyoState: OiyoState;
+  });
+  /** oiyo 状态目录路径 */
+  get stateDir(): string;
+  /** 类型声明文件存放目录 */
+  get typesDir(): string;
+  /** API 全局类型声明文件的完整路径（apis.d.ts） */
+  get declarationPath(): string;
+  /** 判断给定文件路径是否属于已注册的 API 扫描源 */
+  isAutoApiPath(absPath: string): boolean;
+  /** 手动注册值 API 项（来自显式声明，非扫描所得） */
+  includeApi(input: IncludedApi | IncludedApi[]): void;
+  /** 手动注册类型 API 项 */
+  includeApiType(input: IncludedApi | IncludedApi[]): void;
+  /**
+   * 批量注册 API 扫描源（自动去重）
+   * 支持字符串路径或完整的 IncludedApisSource 配置对象
+   */
+  includeApis(input: string | string[] | IncludedApisSource | IncludedApisSource[]): void;
+  /** 解析配置文件中的 scan.apis，分别注册到扫描源或手动注册列表 */
+  private registerConfigScanners;
+  /** 重置所有已收集的状态（在重新扫描前调用） */
+  private resetCollectedState;
+  /**
+   * 注册一个值导出项，处理同名冲突检测
+   * - 同文件同导出名：跳过（重复）
+   * - 同文件但已有具名导出时遇到 default：跳过（具名优先）
+   * - 不同文件同名：冲突警告并跳过
+   * @returns 是否注册成功
+   */
+  private registerValue;
+  /**
+   * 注册一个类型导出项，处理同名冲突检测
+   * 同文件同导出名视为重复跳过，不同文件同名则冲突警告
+   */
+  private registerType;
+  /** 将手动注册的 API 项预先注入注册表（确保优先级高于扫描结果） */
+  private seedIncludedRegistrations;
+  /** 批量注册扫描到的值导出项，跳过 exclude 列表中的名称 */
+  private registerScannedValueItems;
+  /** 批量注册扫描到的类型导出项，跳过 exclude 列表中的名称 */
+  private registerScannedTypeItems;
+  /**
+   * 扫描一组文件，提取导出项并注册到全局注册表
+   * @param source 所属的扫描源配置
+   * @param filePaths 待扫描的文件路径列表
+   * @param scanPath 扫描基准路径（用于计算相对导入路径）
+   * @param options.includeTypes 是否解析类型导出
+   * @param options.registerValues/registerTypes 分别控制是否注册值/类型导出
+   */
+  private scanSourceFiles;
+  /**
+   * 执行完整的 API 收集流程
+   * 1. 重置状态并注入手动注册项
+   * 2. 遍历所有扫描源，分别处理值文件和类型文件
+   * 3. 返回收集到的值 API 列表
+   */
+  collectApis(): Promise<AutoApiItem[]>;
+  /** 代理调用 collectBoundNames，收集代码中已绑定的标识符 */
+  collectBoundNames(code: string): Set<string>;
+  /**
+   * 分析代码中引用了哪些已注册的自动 API，生成对应的 import 语句列表
+   *
+   * @param code
+   * @param options 配置
+   * @param options.boundNames 额外已绑定的标识符（不会被当作需要导入的引用）
+   */
+  resolveImports(code: string, options?: {
+    boundNames?: Iterable<string>;
+  }): string[];
+  resolveImport(name: string): string | undefined;
+  /**
+   * 生成全局类型声明文件内容（apis.d.ts）
+   * 包含两部分：
+   * - 值导出的全局 const 声明（typeof import(...) 形式）
+   * - 类型导出的 re-export 声明
+   */
+  generateDeclaration(): string;
+  /** 生成类型声明内容并写入文件，同时确保 tsconfig 中包含该声明文件 */
+  writeDeclaration(): string;
+}
+//#endregion
+//#region src/modules/auto-component/index.d.ts
+interface AutoComponentFile {
+  componentName: string;
+  exportName: string;
+  filePath: string;
+  importPath?: string;
+}
+interface RegisteredComponent {
+  export?: string;
+  from: string;
+  name: string;
+}
+interface RegisteredComponentsSource {
+  chain?: boolean;
+  ignore?: GlobRule;
+  importBase?: string;
+  pattern?: GlobRule;
+  path: string;
+  prefix?: string;
+}
+declare function resolveScannedComponentSources(config: OiyoConfig): RegisteredComponentsSource[];
+declare function isScannedComponentPath(config: OiyoConfig, absPath: string): boolean;
+declare function resolveComponentName(filePath: string, baseDir: string, options?: {
+  chain?: boolean;
+  prefix?: string;
+}): string;
+declare class OiyoModAutoComponent {
+  private readonly _config;
+  autoComponents: AutoComponentFile[];
+  private readonly registeredComponents;
+  private readonly componentSources;
+  private readonly autoComponentMap;
+  private readonly logger;
+  private readonly oiyoState;
+  constructor(_config: OiyoConfig, deps: {
+    logger: Logger;
+    oiyoState: OiyoState;
+  });
+  get stateDir(): string;
+  get typesDir(): string;
+  get declarationPath(): string;
+  isAutoComponentPath(absPath: string): boolean;
+  registerComponent(component: RegisteredComponent): void;
+  registerComponents(input: string | string[] | RegisteredComponentsSource | RegisteredComponentsSource[]): void;
+  private registerConfigScanners;
+  private setResolvedComponent;
+  collectComponents(): Promise<AutoComponentFile[]>;
+  resolveComponentImports(template: string, importerPath?: string): string[];
+  resolveComponentImport(componentName: string, importerPath?: string): string | undefined;
+  generateDeclaration(): string;
+  writeDeclaration(): string;
+}
+//#endregion
+//#region src/modules/layout/types.d.ts
+/**
+ * 布局信息
+ */
+interface LayoutFile {
+  /** 布局应用名称 */
+  useName: string;
+  /** 布局组件名称 */
+  componentName: string;
+  /** 布局文件的绝对路径 */
+  filePath: string;
+}
+//#endregion
+//#region src/modules/layout/placeholder.d.ts
+declare const OiyoLayout: _$vue.DefineComponent<{}, () => _$vue.VNode<_$vue.RendererNode, _$vue.RendererElement, {
+  [key: string]: any;
+}>[] | undefined, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<_$vue.ExtractPropTypes<{}>>, {}, {}>;
+//#endregion
+//#region src/modules/layout/index.d.ts
+declare class OiyoModLayout {
   private readonly config;
   layoutFiles: LayoutFile[];
-  logger: Logger;
+  private readonly logger;
+  private readonly oiyoState;
   constructor(config: OiyoConfig, deps: {
     logger: Logger;
+    oiyoState: OiyoState;
   });
   get srcDir(): string;
   get layoutDir(): string;
+  get stateDir(): string;
+  get typesDir(): string;
+  get declarationPath(): string;
   isLayoutPath(absPath: string): boolean;
   setLayout(absPath: string): boolean;
   registerLayouts(): Promise<LayoutFile[]>;
+  generateDeclaration(): string;
+  writeDeclaration(): string;
   applyLayout(useName: string | false | undefined, template: string): {
     template: string;
     script: string;
@@ -76,7 +312,7 @@ declare class OiyoLayout {
   };
 }
 //#endregion
-//#region src/root/parse.d.ts
+//#region src/modules/root/parse.d.ts
 interface ParsedRootMarco {
   /** 宏引用模块 */
   imports?: string[];
@@ -91,34 +327,50 @@ interface ParsedRootMarco {
   }[];
 }
 //#endregion
-//#region src/root/virtual-module.d.ts
+//#region src/modules/root/macro.d.ts
+/**
+ * 根上下文工厂函数
+ */
+type RootContextFactory<T extends object> = () => T;
+/**
+ * 定义根上下文
+ * @param factory 返回上下文对象的工厂函数
+ * @returns 上下文对象
+ */
+declare const defineRootContext: <T extends object>(factory: RootContextFactory<T>) => T;
+//#endregion
+//#region src/modules/root/virtual-module.d.ts
 declare const VIRTUAL_ROOT_CONTEXT_ID = "virtual:oiyo-root-context";
 declare const RESOLVED_VIRTUAL_ROOT_CONTEXT_ID = "\0virtual:oiyo-root-context";
 //#endregion
-//#region src/root/index.d.ts
-interface RootView {
-  imports: string[];
-  template: string;
-  script: string;
-}
-declare class OiyoRoot {
+//#region src/modules/root/index.d.ts
+declare class OiyoModRoot {
   readonly config: OiyoConfig;
   /** 根视图模块 */
-  rootView: RootView;
+  rootView: {
+    imports: string[];
+    template: string;
+    script: string;
+  };
   /** 根虚拟模块 */
   rootVM?: string;
   /** 根宏命令结构 */
   rootMarco?: ParsedRootMarco;
-  /** 日志 */
-  logger: Logger;
+  private readonly logger;
+  private readonly oiyoAutoApi?;
   constructor(config: OiyoConfig, deps: {
     logger: Logger;
+    oiyoAutoApi?: OiyoModAutoApi;
   });
   get srcDir(): string;
   get rootPath(): string;
   isRootPath(absPath: string): boolean;
   parseRoot(source: string): {
-    view: RootView;
+    view: {
+      imports: string[];
+      template: string;
+      script: string;
+    };
     marco: ParsedRootMarco | undefined;
   };
   transformRoot(source: string): {
@@ -134,27 +386,104 @@ declare class OiyoRoot {
   };
 }
 //#endregion
-//#region src/page/index.d.ts
-declare class OiyoPage {
+//#region src/modules/route/types.d.ts
+/**
+ * 可序列化的页面元信息值类型
+ * 用于静态提取和 pages.json 生成
+ */
+type PageMetaValue = string | number | boolean | null | PageMetaObject | PageMetaValue[];
+/**
+ * 可序列化的页面元信息对象
+ */
+interface PageMetaObject {
+  [key: string]: PageMetaValue | undefined;
+}
+/**
+ * 页面元信息基础字段
+ */
+interface BasePageMeta {
+  /** 页面类型 */
+  type?: 'page' | 'home';
+  /** 使用的布局名称，false 表示不使用布局 */
+  layout?: string | false;
+  /** uni-app 页面样式配置 */
+  style?: GlobalStyle;
+}
+/**
+ * 已解析的页面元信息
+ * 用于编译期静态提取和 pages.json 生成
+ */
+interface ResolvedPageMeta extends BasePageMeta, PageMetaObject {}
+/**
+ * 页面文件信息
+ */
+interface PageFile {
+  /** 页面路径（相对于 srcDir，不含扩展名） */
+  pagePath: string;
+  /** 页面文件的绝对路径 */
+  filePath: string;
+  /** 页面元信息 */
+  pageMeta: ResolvedPageMeta;
+  /** 所属包（main 或子包名称） */
+  pageBelong: string;
+}
+/**
+ * 已解析的页面配置
+ */
+interface ResolvedPagesJson extends PagesJson {
+  /**
+   * 设置页面路径及窗口表现
+   */
+  pages: Page[];
+}
+//#endregion
+//#region src/modules/route/macro.d.ts
+/**
+ * 页面元信息
+ * 用户在 definePageMeta() 中使用的类型
+ * 支持通过 declare module '@skiyee/oiyo' 进行扩展
+ */
+interface PageMeta extends BasePageMeta {
+  /** 其他自定义字段 */
+  [key: string]: unknown;
+}
+/**
+ * 定义页面元信息
+ * @param meta 页面元信息配置
+ */
+declare const definePageMeta: (meta: PageMeta) => void;
+//#endregion
+//#region src/modules/route/placeholder.d.ts
+declare const OiyoPage: _$vue.DefineComponent<{}, {}, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<_$vue.ExtractPropTypes<{}>>, {}, {}>;
+//#endregion
+//#region src/modules/route/index.d.ts
+declare class OiyoModRoute {
   pageFiles: PageFile[];
   pagesConfig: PagesConfig;
   pagesConfigWatcher?: ConfigWatcher<PagesConfig>;
-  config: OiyoConfig;
-  oiyoRoot?: OiyoRoot;
-  oiyoLayout?: OiyoLayout;
-  logger: Logger;
+  private readonly config;
+  private readonly logger;
+  private readonly oiyoState;
+  private readonly oiyoRoot?;
+  private readonly oiyoLayout?;
   constructor(config: OiyoConfig, deps: {
     logger: Logger;
+    oiyoState: OiyoState;
   });
   constructor(config: OiyoConfig, deps: {
     logger: Logger;
-    oiyoRoot: OiyoRoot;
-    oiyoLayout: OiyoLayout;
+    oiyoState: OiyoState;
+    oiyoRoot: OiyoModRoot;
+    oiyoLayout: OiyoModLayout;
   });
   get srcDir(): string;
   get mainPageDir(): string;
   get subPageDirs(): string[];
   get pagesJsonPath(): string;
+  get stateDir(): string;
+  get typesDir(): string;
+  get declarationPath(): string;
+  resolvePagesJson(userPageJson?: PagesConfig): ResolvedPagesJson;
   loadPagesConfig(): Promise<PagesConfig>;
   watchPagesConfig(onUpdateCallback?: () => void | Promise<void>): Promise<void>;
   unwatchPagesConfig(): Promise<void>;
@@ -177,6 +506,8 @@ declare class OiyoPage {
    * 生成并写入 pages.json
    */
   writePagesJson(userPageJson?: PagesConfig): void;
+  generateDeclaration(userPageJson?: PagesConfig): string;
+  writeDeclaration(userPageJson?: PagesConfig): string;
   /**
    * 注册所有页面
    * - 扫描页面
@@ -191,7 +522,24 @@ declare class OiyoPage {
   }>;
 }
 //#endregion
+//#region src/plugin/context.d.ts
+interface OiyoContext {
+  config: OiyoConfig;
+  autoApi: OiyoModAutoApi;
+  autoComponent: OiyoModAutoComponent;
+  logger: Logger;
+  layout: OiyoModLayout;
+  state: OiyoState;
+  route: OiyoModRoute;
+  root: OiyoModRoot;
+}
+//#endregion
 //#region src/plugin/index.d.ts
+declare module 'vite' {
+  interface UserConfig {
+    oiyo: OiyoContext;
+  }
+}
 declare function OiyoCorePlugin(options?: OiyoConfig): Plugin[];
 //#endregion
-export { LogErrorOptions, LogLevel, LogLevels, LogOptions, LogType, Logger, LoggerOptions, OiyoCorePlugin, OiyoLayout, OiyoPage, OiyoRoot, RESOLVED_VIRTUAL_ROOT_CONTEXT_ID, RootView, VIRTUAL_ROOT_CONTEXT_ID, createLogger };
+export { type AutoApiItem, AutoComponentFile, type IncludedApi, type IncludedApisSource, LogErrorOptions, LogLevel, LogLevels, LogOptions, LogType, Logger, LoggerOptions, OiyoCorePlugin, OiyoLayout, OiyoModAutoApi, OiyoModAutoComponent, OiyoModLayout, OiyoModRoot, OiyoModRoute, OiyoPage, OiyoState, type PageMeta, RESOLVED_VIRTUAL_ROOT_CONTEXT_ID, RegisteredComponent, RegisteredComponentsSource, VIRTUAL_ROOT_CONTEXT_ID, createLogger, definePageMeta, defineRootContext, isScannedComponentPath, resolveComponentName, resolveScannedComponentSources };