@univer-cli/api-reference 1.0.0-beta.2

package/README.md

@@ -0,0 +1,67 @@
+# @univer-cli/api-reference
+
+English | [简体中文](./README.zh-CN.md)
+
+Search and consult the Univer Facade API locally without launching Univer or accessing online documentation.
+
+When you know only what you want to accomplish, search by keyword. When you know the exact symbol, inspect structured details for classes, members, types, and enums. Query results are ordinary TypeScript data that a CLI, Agent, editor tool, or custom interface can process further.
+
+## Installation
+
+```bash
+pnpm add @univer-cli/api-reference
+```
+
+Requires Node.js 22.12 or higher.
+
+## Quick Start
+
+The package includes a reference generated from the current Univer SDK declarations:
+
+```ts
+import { createStandardApiReference } from "@univer-cli/api-reference";
+
+const reference = createStandardApiReference();
+
+const matches = reference.find({
+  terms: ["setValues", "conditional formatting"],
+  unit: "sheet",
+  limit: 20,
+});
+
+const details = reference.show(["FRange", "FRange.setValues", "ICellData.v"]);
+```
+
+`find()` returns matches for each keyword and is useful for discovering APIs. `show()` returns precise details for each symbol and is useful for generating instructions or validating input.
+
+## Query rules
+
+- Search is case-insensitive and supports substrings, camelCase word splitting, and fuzzy matching.
+- `unit` can restrict results to `sheet`, `slide`, `doc`, `base`, or `board`; shared APIs are always
+  included.
+- `limit` works on each search term, not the sum of all results.
+- Details include inheritance, composition, overloads, related types, and spelling suggestions.
+- Common class names can use aliases, for example, `range` will be resolved to `FRange`.
+- When the symbol does not exist, `status: "not-found"` is returned and no exception is thrown.
+
+## Load your own reference
+
+If your application needs to pin a different API dataset, load a prebuilt artifact:
+
+```ts
+import { loadApiReference } from "@univer-cli/api-reference";
+
+const reference = loadApiReference(artifact);
+```
+
+Artifact is a versioned opaque value. The package verifies the format when loading; callers should not rely on its internal index structure.
+
+For the preset command, see
+[`@univer-cli/api-reference-command`](../api-reference-command/README.md).
+
+## API entry
+
+- `createStandardApiReference()`: Create reference using built-in Univer declarations.
+- `loadApiReference(artifact)`: Verify and load pre-generated artifacts.
+- `ApiReference.find()`: Discover APIs by keyword.
+- `ApiReference.show()`: Inspect details by symbol.

package/README.zh-CN.md

@@ -0,0 +1,67 @@
+# @univer-cli/api-reference
+
+[English](./README.md) | 简体中文
+
+在本地搜索和查阅 Univer Facade API，无需启动 Univer，也无需访问在线文档。
+
+当你只知道“想完成什么”，可以用关键词查找相关 API；当你已经知道 symbol，可以查看 class、member、type 或
+enum 的结构化详情。查询结果是普通 TypeScript 数据，适合交给 CLI、Agent、编辑器工具或自定义界面继续处理。
+
+## 安装
+
+```bash
+pnpm add @univer-cli/api-reference
+```
+
+要求 Node.js 22.12 或更高版本。
+
+## 快速开始
+
+Package 自带一份与当前 Univer SDK declarations 对应的 reference：
+
+```ts
+import { createStandardApiReference } from "@univer-cli/api-reference";
+
+const reference = createStandardApiReference();
+
+const matches = reference.find({
+  terms: ["setValues", "conditional formatting"],
+  unit: "sheet",
+  limit: 20,
+});
+
+const details = reference.show(["FRange", "FRange.setValues", "ICellData.v"]);
+```
+
+`find()` 按关键词分别返回候选项，适合发现 API；`show()` 按 symbol 返回精确详情，适合生成说明或校验输入。
+
+## 查询规则
+
+- 搜索不区分大小写，支持 substring、camelCase 分词和模糊匹配。
+- `unit` 可限定为 `sheet`、`slide`、`doc`、`base` 或 `board`，shared API 始终保留。
+- `limit` 作用于每个搜索词，而不是所有结果的总和。
+- 详情包含继承、组合、overload、相关类型和拼写建议。
+- 常用 class 名可使用别名，例如 `range` 会解析为 `FRange`。
+- symbol 不存在时返回 `status: "not-found"`，不会抛出异常。
+
+## 加载自己的 reference
+
+如果 application 需要固定另一份 API 数据，可以加载预生成 artifact：
+
+```ts
+import { loadApiReference } from "@univer-cli/api-reference";
+
+const reference = loadApiReference(artifact);
+```
+
+Artifact 是带版本的 opaque value。Package 会在加载时校验格式；调用方不应依赖其内部索引结构。
+
+预设 command 见
+[`@univer-cli/api-reference-command`](../api-reference-command/README.zh-CN.md)。
+
+## API 入口
+
+- `createStandardApiReference()`：使用内置 Univer declarations 创建 reference。
+- `loadApiReference(artifact)`：校验并加载预生成 artifact。
+- `ApiReference.find()`：按关键词发现 API。
+- `ApiReference.show()`：按 symbol 查看详情。

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';module['exports']=require('./index.mjs');

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+//#region src/index.d.ts
+declare const API_REFERENCE_UNITS: readonly ["sheet", "slide", "doc", "base", "board"];
+type ApiReferenceUnit = (typeof API_REFERENCE_UNITS)[number];
+type ApiReferenceMemberKind = "method" | "getter" | "property" | "function-property";
+type ApiReferenceMemberRelation = "own" | "inherited" | "composed";
+type ApiReferenceTypeKind = "interface" | "enum" | "alias";
+interface ApiReferenceMember {
+  readonly packageName: string;
+  readonly owner: string;
+  readonly kind: ApiReferenceMemberKind;
+  readonly readonly?: boolean;
+  readonly name: string;
+  readonly signature: string;
+  readonly summary: string;
+  readonly example: string;
+}
+interface ApiReferenceTypeMember {
+  readonly name: string;
+  readonly optional?: boolean;
+  readonly type: string;
+  readonly summary?: string;
+}
+interface ApiReferenceType {
+  readonly kind: ApiReferenceTypeKind;
+  readonly packageName: string;
+  readonly name: string;
+  readonly summary: string;
+  readonly members?: readonly ApiReferenceTypeMember[];
+  readonly values?: readonly {
+    readonly name: string;
+    readonly value: string | number;
+  }[];
+  readonly definition?: string;
+  readonly extends?: string;
+  readonly aliases?: readonly string[];
+}
+interface FindApiReferencesInput {
+  readonly terms: readonly string[];
+  readonly unit?: ApiReferenceUnit;
+  readonly limit?: number;
+}
+interface ApiReferenceFindMatch {
+  readonly kind: ApiReferenceMemberKind | ApiReferenceTypeKind | "field";
+  readonly label: string;
+  readonly signature: string;
+  readonly summary: string;
+  readonly packageName: string;
+  readonly score: number;
+}
+interface ApiReferenceFindTermResult {
+  readonly term: string;
+  readonly matches: readonly ApiReferenceFindMatch[];
+  readonly totalMatches: number;
+}
+interface ApiReferenceMemberGroup {
+  readonly owner: string;
+  readonly relation: ApiReferenceMemberRelation;
+  readonly members: readonly ApiReferenceMember[];
+}
+interface ApiReferenceClassResult {
+  readonly status: "found";
+  readonly kind: "class";
+  readonly query: string;
+  readonly name: string;
+  readonly lineage: readonly string[];
+  readonly composes: readonly string[];
+  readonly groups: readonly ApiReferenceMemberGroup[];
+}
+interface ApiReferenceMemberResultEntry {
+  readonly member: ApiReferenceMember;
+  readonly relation: ApiReferenceMemberRelation;
+  readonly relationOwner: string;
+  readonly appendix: readonly ApiReferenceType[];
+}
+interface ApiReferenceMemberResult {
+  readonly status: "found";
+  readonly kind: "member";
+  readonly query: string;
+  readonly target: string;
+  readonly entries: readonly ApiReferenceMemberResultEntry[];
+}
+interface ApiReferenceTypeResult {
+  readonly status: "found";
+  readonly kind: "type";
+  readonly query: string;
+  readonly type: ApiReferenceType;
+  readonly inherited: readonly ApiReferenceType[];
+  readonly appendix: readonly ApiReferenceType[];
+}
+interface ApiReferenceTypeMemberResult {
+  readonly status: "found";
+  readonly kind: "type-member";
+  readonly query: string;
+  readonly declaredBy: ApiReferenceType;
+  readonly requestedType: ApiReferenceType;
+  readonly member: ApiReferenceTypeMember | {
+    readonly name: string;
+    readonly value: string | number;
+  };
+  readonly appendix: readonly ApiReferenceType[];
+}
+interface ApiReferenceNotFoundResult {
+  readonly status: "not-found";
+  readonly kind: "symbol" | "member";
+  readonly query: string;
+  readonly owner?: string;
+  readonly member?: string;
+  readonly suggestions: readonly string[];
+}
+type ApiReferenceShowResult = ApiReferenceClassResult | ApiReferenceMemberResult | ApiReferenceTypeResult | ApiReferenceTypeMemberResult | ApiReferenceNotFoundResult;
+interface ApiReference {
+  find(input: FindApiReferencesInput): readonly ApiReferenceFindTermResult[];
+  show(symbols: readonly string[]): readonly ApiReferenceShowResult[];
+}
+declare class ApiReferenceArtifactError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+declare function loadApiReferenceArtifact(serialized: string): ApiReference;
+declare function createStandardApiReference(): ApiReference;
+//#endregion
+export { API_REFERENCE_UNITS, ApiReference, ApiReferenceArtifactError, ApiReferenceClassResult, ApiReferenceFindMatch, ApiReferenceFindTermResult, ApiReferenceMember, ApiReferenceMemberGroup, ApiReferenceMemberKind, ApiReferenceMemberRelation, ApiReferenceMemberResult, ApiReferenceMemberResultEntry, ApiReferenceNotFoundResult, ApiReferenceShowResult, ApiReferenceType, ApiReferenceTypeKind, ApiReferenceTypeMember, ApiReferenceTypeMemberResult, ApiReferenceTypeResult, ApiReferenceUnit, FindApiReferencesInput, createStandardApiReference, loadApiReferenceArtifact };