feat: update code comment (#832)

hustcc · gemini-code-assist[bot] · web-flow · commit ae3b9afe9eea · 2025-11-04T10:55:35.000+08:00
* build: remove unused files

* docs: add comment

* Update packages/ava/src/advisor/advisor.ts

Co-authored-by: gemini-code-assist[bot] &lt;176961590+gemini-code-assist[bot]@users.noreply.github.com&gt;

* Update packages/ava/package.json

Co-authored-by: gemini-code-assist[bot] &lt;176961590+gemini-code-assist[bot]@users.noreply.github.com&gt;

---------

Co-authored-by: gemini-code-assist[bot] &lt;176961590+gemini-code-assist[bot]@users.noreply.github.com&gt;
diff --git a/packages/ava/.fatherrc.ts b/packages/ava/.fatherrc.ts
@@ -1,9 +1,16 @@
-import fatherConfig from '../../.fatherrc';
 import path from 'path';
+import { defineConfig } from 'father';
 
-export default fatherConfig('ts', 'AVA', {
+export default defineConfig({
+  umd: {
+    name: 'AVA',
+    output: 'dist',
+  },
   alias: {
     '@ava': path.resolve(__dirname, 'src'),
+    '@ava/advisor-deprecated': path.resolve(__dirname, 'src/advisor-deprecated'),
     '@advisor': path.resolve(__dirname, 'src/advisor'),
+    '@advisor-deprecated': path.resolve(__dirname, 'src/advisor-deprecated'),
+    '@ava/insight': path.resolve(__dirname, 'src/insight'),
   }
 });
diff --git a/packages/ava/package.json b/packages/ava/package.json
@@ -1,26 +1,17 @@
 {
   "name": "@antv/ava",
   "version": "4.0.0-alpha.0",
-  "description": "A framework for automated visual analytics.",
-  "author": {
-    "name": "AntV",
-    "url": "https://antv.antgroup.com/"
-  },
-  "homepage": "https://ava.antv.antgroup.com",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/antvis/AVA/tree/master/packages/ava"
-  },
+  "description": "A framework for AI driven Visual Analytics.",
   "sideEffects": false,
   "keywords": [
+    "antv",
+    "ava",
+    "ai",
+    "visual-analytics",
     "visualization",
     "augmented-analytics",
     "insight"
   ],
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "unpkg": "dist/ava.min.js",
@@ -31,21 +22,13 @@
     "lib"
   ],
   "scripts": {
-    "lint": "eslint --ext .js,.jsx,.ts,.tsx './'",
-    "lint-fix": "npm run lint -- --fix",
-    "prettier": " prettier --check '**/*' --ignore-path=../../.prettierignore",
-    "prettier-fix": "npm run prettier -- --write",
-    "format": "npm run prettier-fix && npm run lint-fix",
-    "lint-staged": "lint-staged",
     "clean": "rimraf lib esm dist",
     "build:umd": "father build",
-    "build:cjs": "rimraf ./lib && tsc -p tsconfig.cjs.json && tsc-alias -p tsconfig.cjs.json",
-    "build:esm": "rimraf ./esm && tsc -p tsconfig.esm.json && tsc-alias -p tsconfig.esm.json",
-    "build:ntv-schema": "mkdir -p build && ts-json-schema-generator -f tsconfig.json -p src/text/index.ts -t NarrativeTextSpec --no-type-check --no-ref-encode > build/ntv-schema.json",
+    "build:esm": "rimraf esm && tsc --module esnext --target es6 --outDir ./esm",
+    "build:cjs": "rimraf lib && tsc --module commonjs --target es6 --outDir ./lib",
     "build": "run-p build:*",
     "test": "jest",
-    "coverage": "jest --coverage",
-    "watch": "yarn module && yarn build --w"
+    "coverage": "jest --coverage"
   },
   "lint-staged": {
     "*.{ts,tsx}": [
@@ -74,6 +57,7 @@
     "@stdlib/types": "^0.0.12",
     "@testing-library/jest-dom": "^4.2.4",
     "@types/d3-array": "^3.0.1",
+    "@types/d3-dispatch": "3.0.2",
     "@types/jest": "^30.0.0",
     "@types/lodash": "^4.14.171",
     "@types/numeral": "^2.0.2",
@@ -84,9 +68,22 @@
     "npm-run-all": "^4.1.5",
     "numeral": "^2.0.6",
     "prettier": "^2.4.1",
-    "rimraf": "^3.0.2",
+    "rimraf": "^6.1.0",
     "ts-json-schema-generator": "^1.1.2",
     "tsc-alias": "^1.8.10",
     "typescript": "^4.9.3"
+  },
+  "author": {
+    "name": "AntV",
+    "url": "https://antv.antgroup.com/"
+  },
+  "homepage": "https://ava.antv.antgroup.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/antvis/AVA"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
   }
 }
diff --git a/packages/ava/src/advisor/advisor.ts b/packages/ava/src/advisor/advisor.ts
@@ -9,57 +9,98 @@ import {
 } from '../types';
 import { extractData } from '../data';
 import { AdviseChartPipeline } from './advise-chart-pipeline/pipeline';
-import { AdviseTextPipeline } from './advise-text-pipeline/pipeline';
 import { RENDERER, type Spec } from '../bind';
 
+/**
+ * The 1st level advisor class.
+ * Used to extract data, recommend charts, and render charts. All functionalities are AI-driven.
+ */
 export class Advisor {
 
-  config!: AdvisorConfig;
+  /**
+   * Configuration for the advisor. Includes LLM settings, chart inclusion/exclusion lists.
+   */
+  private config!: AdvisorConfig;
 
   adviseChartPipeline: BasePipeline<AdviseChartParams>;
 
-  adviseTextPipeline: BasePipeline<AdviseTextParams>;
-
   constructor(config: AdvisorConfig = {}) {
     this.config = config;
+
+    // Initialize pipelines.
     this.adviseChartPipeline = new AdviseChartPipeline({
       config,
     });
-    this.adviseTextPipeline = new AdviseTextPipeline({
-      config,
-    });
   }
 
+  /**
+   * Extract data shards from raw data or user query.
+   * 
+   * Case 1 - User provides a text query, extract relevant data shards:
+   * 
+      advisor.extract('What is the average age of people who work as engineers?');
+   * 
+   * Case 2 - User provides a query with raw data:
+   * 
+      advisor.extract(`帮我可视化以下数据：
+        城市 类别 渠道 销售额 价格
+        杭州 体育 A  100  80
+        北京 体育 A  200  90
+        上海 体育 B  150  85
+        广州 体育 B  120  70
+        深圳 体育 C  180  95
+      `);
+   * 
+   * Case 3 - User provides raw data, extract data shards directly:
+   * 
+      advisor.extract({ type: 'A', value: 2 });
+   */
   async extract(params: AdviseChartParams) {
     const { purpose, data } = params;
     const input = purpose ?? data;
     const dataShards = await extractData(input, { llmConfig: this.config.llm });
     return dataShards;
   }
 
-  // eslint-disable-next-line no-dupe-class-members
+  /**
+   * Advise charts based on the data shards, which are extracted from the `advisor.extract` API.
+   * This is the core function of the Advisor class, which leverages LLMs to recommend suitable chart types and encodings based on the provided data and user purpose.
+   * 
+   * const advises = advisor.advise(dataShards);
+   */
   advise(params: AdviseChartParams): Promise<AdviseStageOutput>;
-
-  // eslint-disable-next-line no-dupe-class-members
   advise(params: AdviseTextParams): Promise<AdviseText>;
-
-  // Actual implementation
-  // eslint-disable-next-line no-dupe-class-members
   async advise(params: AdviseChartParams | AdviseTextParams): Promise<AdviseStageOutput | AdviseText> {
     const result = await this.adviseChartPipeline.execute(params as AdviseChartParams);
     return result;
-    // recommend text
-    // TODO: implement text recommendation
-    // await this.adviseTextPipeline.execute(params as AdviseTextParams);
-    // return {} as AdviseText;
   }
 
+  /**
+   * Render the chart recommendation spec into a chart dom. We can use different renderers by customizing the renderer.
+   * 
+   * Case 1 - Using default renderer (AVA built-in):
+   * 
+      advisor.render({
+        container: '#chart',
+        spec: chartSpec,
+      });
+   * 
+   * Case 2 - Using custom renderer:
+   * 
+      const customRenderer: Renderer = (container, spec) => { ... };
+      bindRenderer(customRenderer);
+      advisor.render({
+        container: '#chart',
+        spec: chartSpec,
+      });
+   * 
+   */
   render(params: { container: string; spec: Spec }) {
     if (RENDERER) {
       const { container, spec } = params;
       return RENDERER(container, spec);
     }
-    logError('Chart render not configured');
+    logError('Chart render not configured, please bind a renderer first, GPT-Vis is recommended.');
     return null;
   }
 }
diff --git a/packages/ava/src/advisor/index.ts b/packages/ava/src/advisor/index.ts
@@ -1 +1 @@
-export { Advisor, bindRenderer } from './advisor';
+export { Advisor } from './advisor';
diff --git a/packages/ava/tsconfig.cjs.json b/packages/ava/tsconfig.cjs.json
diff --git a/packages/ava/tsconfig.esm.json b/packages/ava/tsconfig.esm.json
diff --git a/packages/ava/tsconfig.json b/packages/ava/tsconfig.json
@@ -1,4 +1,29 @@
 {
-  "extends": "../../tsconfig.json",
-  "include": ["./src", "./__tests__"]
+  "compilerOptions": {
+    "module": "ESNext",
+    "target": "es6",
+    "jsx": "preserve",
+    "importHelpers": true,
+    "moduleResolution": "node",
+    "experimentalDecorators": true,
+    "declaration": true,
+    "sourceMap": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "noEmitOnError": false,
+    "pretty": true,
+    "lib": ["dom", "esnext"],
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "baseUrl": ".",
+    "paths": {
+      "@antv/ava": ["src/index.ts"],
+      "@ava/*": ["src/*"],
+      "@advisor/*": ["src/advisor/*"],
+      "@ava/advisor-deprecated/*": ["src/advisor-deprecated/*"],
+      "@ava/insight/*": ["src/insight/*"]
+    }
+  },
+  "include": ["src/**/*"]
 }

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-export { Advisor, bindRenderer } from './advisor';`
	`1`	`+export { Advisor } from './advisor';`