AGENTS.md

1# AGENTS.md
2 
3## Overview
4 
5Apache ECharts is a TypeScript-first charting library. Most runtime code lives in `src/`, while build scripts, test utilities, and packaging logic live alongside it in dedicated top-level folders.
6 
7One thing worth knowing early is that this repo is assembled through explicit registration and curated entry files. New runtime code often needs to be connected not only in its local module, but also through public exports or bundle entry files before it becomes part of a user-facing build.
8 
9## Contributor Docs
10 
11When a task touches contribution workflow, prefer the repo's own contributor-facing documents over this summary:
12 
13- `CONTRIBUTING.md` for general contribution guidance
14- `https://github.com/apache/echarts/wiki/How-to-make-a-pull-request` for PR workflow, test expectations, and git message conventions
15- `https://github.com/apache/echarts/wiki/How-to-setup-the-dev-environment` for local setup and zrender-linked development
16- `https://github.com/apache/echarts/wiki/Security-Checklist-for-Code-Contributors` for security-sensitive API and API-design checks
17- `.github/pull_request_template.md` for PR structure
18- `.github/workflows/` for CI expectations
19 
20This file is only a short orientation note. If there is any conflict, the repo's dedicated contributor docs should win.
21 
22A few stable rules from the PR wiki are especially worth keeping in mind:
23 
24- In non-release PRs, avoid committing `dist/`, `i18n/`, and `ssr/client/dist/`.
25- Follow the repo's PR template when opening or updating a pull request.
26- Git messages follow the repo convention: `<type>(<scope>): <subject>. close #<issue_id>`, with the issue-closing suffix omitted when there is no related issue.
27- If you need to work on linked `zrender` code, the dev-environment wiki recommends using an absolute symlink at `node_modules/zrender` instead of `npm link`, because the watch flow depends on that setup.
28- Be cautious with security-sensitive web APIs such as `innerHTML`, arbitrary DOM selectors, `eval`-like execution, raw style injection, and navigation-related APIs. If a feature must allow that kind of behavior, the security checklist expects clear documentation warnings.
29 
30## Project Layout
31 
32- `src/`: built-in charts, components, coordinate systems, models, renderers, features, themes, and i18n source
33- `src/export/*.ts`: public modular export surfaces
34- `src/echarts.all.ts`, `src/echarts.common.ts`, `src/echarts.simple.ts`, `src/echarts.ts`: main bundle entry files
35- `extension-src/`: separately packaged extensions
36- `ssr/client/src/`: SSR client source
37- `build/`: build, packaging, prepublish, and generation scripts
38- `test/ut/spec/`: Jest unit tests
39- `test/*.html`: browser-based rendering and interaction cases
40 
41## Source And Generated Files
42 
43In general, `src/` is the main source of truth for built-in library behavior.
44 
45Some top-level files and folders are generated or packaging-oriented:
46 
47- `i18n/*.js` and `i18n/*-obj.js` are generated from `src/i18n/*.ts`
48- `lib/`, `types/`, `extension/`, `ssr/client/lib/`, `ssr/client/types/`, and root `index*.js` are produced by the build/prepublish flow
49- `dist/` contains build output
50 
51The top-level `theme/*.js` files are packaged theme sources rather than normal `src/theme/` runtime modules, so they are best treated separately from the generated locale/build artifacts above.
52 
53## Exports And Entry Files
54 
55This repo exposes functionality at a few different layers:
56 
57- local runtime modules under `src/`
58- modular public exports under `src/export/*.ts`
59- bundled entry files under `src/echarts*.ts`
60 
61Because of that structure, changes to charts, components, renderers, or features sometimes need corresponding updates in exports or entry files to show up in the expected public build.
62 
63## Testing
64 
65The repository uses two main testing styles:
66 
67- Jest tests in `test/ut/spec/` for logic-heavy behavior such as models, utilities, data transforms, and API behavior
68- HTML cases in `test/` for rendering, layout, interaction, and visual regressions
69 
70For local development, `npm run dev` starts the watch build and opens the `test/` directory. New HTML cases can be scaffolded with `npm run mktest`.
71 
72## Common Checks
73 
74- `npm run checktype`
75- `npm run lint`
76- `npm test`
77- `npm run test:dts:fast`
78- `npm run dev`
79 
80## Style Notes
81 
82This repository consistently keeps ASF license headers in source and test files, and the codebase style is stable: single quotes, semicolons, and 4-space indentation are the norm. Small changes that follow nearby patterns tend to fit best here.
83