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

package/README.md

@@ -4,7 +4,7 @@ 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.
+When no relevant class or API symbol is known, search the installed index using API-name keywords or identifier fragments. When a class or exact symbol is known, 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
 
@@ -24,23 +24,31 @@ import { createStandardApiReference } from "@univer-cli/api-reference";
 const reference = createStandardApiReference();
 
 const matches = reference.find({
-  terms: ["setValues", "conditional formatting"],
+  terms: ["setValues", "conditionalformat"],
   unit: "sheet",
   limit: 20,
 });
 
-const details = reference.show(["FRange", "FRange.setValues", "ICellData.v"]);
+const details = reference.show([
+  "FRange",
+  "FRange.setValues",
+  "ConditionalFormatHighlightRuleBuilder.setRanges",
+  "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.
+`find()` returns matches for each keyword and is useful for discovering API symbols. Pass a useful symbol returned by `find()` directly to `show()`. `show()` returns precise details for each symbol and is useful for generating instructions or validating input. Show results retain declaration headers, overloads, structured JSDoc, declaration-source relations, and directly referenced types so adapters can render a supported public declaration projection without reparsing `.d.ts` files.
 
 ## Query rules
 
-- Search is case-insensitive and supports substrings, camelCase word splitting, and fuzzy matching.
+- `find()` searches by API-name keyword or identifier fragment. It is case-insensitive and supports substrings, camelCase word splitting, and fuzzy identifier matching.
+- Each search term is handled independently and returns its own matches. Terms are not combined as AND, and `find()` does not interpret intent.
 - `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.
+- Details include exact declarations, structured JSDoc, inheritance, composition, overloads, related
+  types, and spelling suggestions.
+- Classes reached through public Facade signatures can be inspected even when they are chain-only return types rather than directly exported Facade roots.
 - 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.
 
@@ -49,9 +57,9 @@ const details = reference.show(["FRange", "FRange.setValues", "ICellData.v"]);
 If your application needs to pin a different API dataset, load a prebuilt artifact:
 
 ```ts
-import { loadApiReference } from "@univer-cli/api-reference";
+import { loadApiReferenceArtifact } from "@univer-cli/api-reference";
 
-const reference = loadApiReference(artifact);
+const reference = loadApiReferenceArtifact(artifact);
 ```
 
 Artifact is a versioned opaque value. The package verifies the format when loading; callers should not rely on its internal index structure.
@@ -62,6 +70,6 @@ For the preset command, see
 ## API entry
 
 - `createStandardApiReference()`: Create reference using built-in Univer declarations.
-- `loadApiReference(artifact)`: Verify and load pre-generated artifacts.
+- `loadApiReferenceArtifact(artifact)`: Verify and load pre-generated artifacts.
 - `ApiReference.find()`: Discover APIs by keyword.
 - `ApiReference.show()`: Inspect details by symbol.

package/README.zh-CN.md

@@ -4,8 +4,7 @@
 
 在本地搜索和查阅 Univer Facade API，无需启动 Univer，也无需访问在线文档。
 
-当你只知道“想完成什么”，可以用关键词查找相关 API；当你已经知道 symbol，可以查看 class、member、type 或
-enum 的结构化详情。查询结果是普通 TypeScript 数据，适合交给 CLI、Agent、编辑器工具或自定义界面继续处理。
+不知道相关 class 或 API symbol 时，可以用 API 名关键词或 identifier fragment 搜索已安装的索引；已知 class 或准确 symbol 时，可以查看 class、member、type 或 enum 的结构化详情。查询结果是普通 TypeScript 数据，适合交给 CLI、Agent、编辑器工具或自定义界面继续处理。
 
 ## 安装
 
@@ -25,22 +24,29 @@ import { createStandardApiReference } from "@univer-cli/api-reference";
 const reference = createStandardApiReference();
 
 const matches = reference.find({
-  terms: ["setValues", "conditional formatting"],
+  terms: ["setValues", "conditionalformat"],
   unit: "sheet",
   limit: 20,
 });
 
-const details = reference.show(["FRange", "FRange.setValues", "ICellData.v"]);
+const details = reference.show([
+  "FRange",
+  "FRange.setValues",
+  "ConditionalFormatHighlightRuleBuilder.setRanges",
+  "ICellData.v",
+]);
 ```
 
-`find()` 按关键词分别返回候选项，适合发现 API；`show()` 按 symbol 返回精确详情，适合生成说明或校验输入。
+`find()` 按关键词分别返回候选项，适合发现 API symbol。将 `find()` 返回的有用 symbol 直接传给 `show()`；`show()` 按 symbol 返回精确详情，适合生成说明或校验输入。Show 结果会保留 declaration header、overload、结构化 JSDoc、声明来源关系和直接引用的 type，使 adapter 无需重新解析 `.d.ts` 就能渲染受支持的公开声明投影。
 
 ## 查询规则
 
-- 搜索不区分大小写，支持 substring、camelCase 分词和模糊匹配。
+- `find()` 按 API 名关键词或 identifier fragment 搜索，不区分大小写，支持 substring、camelCase 分词和 identifier 模糊匹配。
+- 每个搜索词都独立处理并分别返回结果；多个搜索词不会按 AND 组合，`find()` 也不会解释意图。
 - `unit` 可限定为 `sheet`、`slide`、`doc`、`base` 或 `board`，shared API 始终保留。
 - `limit` 作用于每个搜索词，而不是所有结果的总和。
-- 详情包含继承、组合、overload、相关类型和拼写建议。
+- 详情包含精确声明、结构化 JSDoc、继承、组合、overload、相关类型和拼写建议。
+- 公开 Facade 签名可达的 class 即使只是链式返回类型、不是直接导出的 Facade root，也可以查询。
 - 常用 class 名可使用别名，例如 `range` 会解析为 `FRange`。
 - symbol 不存在时返回 `status: "not-found"`，不会抛出异常。
 
@@ -49,9 +55,9 @@ const details = reference.show(["FRange", "FRange.setValues", "ICellData.v"]);
 如果 application 需要固定另一份 API 数据，可以加载预生成 artifact：
 
 ```ts
-import { loadApiReference } from "@univer-cli/api-reference";
+import { loadApiReferenceArtifact } from "@univer-cli/api-reference";
 
-const reference = loadApiReference(artifact);
+const reference = loadApiReferenceArtifact(artifact);
 ```
 
 Artifact 是带版本的 opaque value。Package 会在加载时校验格式；调用方不应依赖其内部索引结构。
@@ -62,6 +68,6 @@ Artifact 是带版本的 opaque value。Package 会在加载时校验格式；
 ## API 入口
 
 - `createStandardApiReference()`：使用内置 Univer declarations 创建 reference。
-- `loadApiReference(artifact)`：校验并加载预生成 artifact。
+- `loadApiReferenceArtifact(artifact)`：校验并加载预生成 artifact。
 - `ApiReference.find()`：按关键词发现 API。
 - `ApiReference.show()`：按 symbol 查看详情。

package/dist/index.d.ts

@@ -4,6 +4,16 @@ 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 ApiReferenceDocumentationTag {
+  readonly name: string;
+  readonly subject?: string;
+  readonly type?: string;
+  readonly text: string;
+}
+interface ApiReferenceDocumentation {
+  readonly description: string;
+  readonly tags: readonly ApiReferenceDocumentationTag[];
+}
 interface ApiReferenceMember {
   readonly packageName: string;
   readonly owner: string;
@@ -13,18 +23,23 @@ interface ApiReferenceMember {
   readonly signature: string;
   readonly summary: string;
   readonly example: string;
+  readonly documentation?: ApiReferenceDocumentation;
 }
 interface ApiReferenceTypeMember {
   readonly name: string;
   readonly optional?: boolean;
   readonly type: string;
+  readonly declaration?: string;
   readonly summary?: string;
+  readonly documentation?: ApiReferenceDocumentation;
 }
 interface ApiReferenceType {
   readonly kind: ApiReferenceTypeKind;
   readonly packageName: string;
   readonly name: string;
+  readonly declaration?: string;
   readonly summary: string;
+  readonly documentation?: ApiReferenceDocumentation;
   readonly members?: readonly ApiReferenceTypeMember[];
   readonly values?: readonly {
     readonly name: string;
@@ -33,6 +48,7 @@ interface ApiReferenceType {
   readonly definition?: string;
   readonly extends?: string;
   readonly aliases?: readonly string[];
+  readonly signatures?: readonly string[];
 }
 interface FindApiReferencesInput {
   readonly terms: readonly string[];
@@ -62,6 +78,10 @@ interface ApiReferenceClassResult {
   readonly kind: "class";
   readonly query: string;
   readonly name: string;
+  readonly packageName: string;
+  readonly declarationKind: "class" | "alias";
+  readonly declaration: string;
+  readonly documentation?: ApiReferenceDocumentation;
   readonly lineage: readonly string[];
   readonly composes: readonly string[];
   readonly groups: readonly ApiReferenceMemberGroup[];
@@ -118,4 +138,4 @@ declare class ApiReferenceArtifactError extends Error {
 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 };
+export { API_REFERENCE_UNITS, ApiReference, ApiReferenceArtifactError, ApiReferenceClassResult, ApiReferenceDocumentation, ApiReferenceDocumentationTag, ApiReferenceFindMatch, ApiReferenceFindTermResult, ApiReferenceMember, ApiReferenceMemberGroup, ApiReferenceMemberKind, ApiReferenceMemberRelation, ApiReferenceMemberResult, ApiReferenceMemberResultEntry, ApiReferenceNotFoundResult, ApiReferenceShowResult, ApiReferenceType, ApiReferenceTypeKind, ApiReferenceTypeMember, ApiReferenceTypeMemberResult, ApiReferenceTypeResult, ApiReferenceUnit, FindApiReferencesInput, createStandardApiReference, loadApiReferenceArtifact };