diff --git a/.cursor/rules/main.mdc b/.cursor/rules/main.mdc new file mode 100644 index 000000000..eef7fd7ce --- /dev/null +++ b/.cursor/rules/main.mdc @@ -0,0 +1,6 @@ +--- +description: Project-wide guidance for AI agents working in this repository +alwaysApply: true +--- + +All guidance for AI agents working in this repository lives in [AGENTS.md](mdc:AGENTS.md) at the repository root. Read it first. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..ee5b0ee7d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# AGENTS.md + +Instructions for AI coding agents (Cursor, Claude Code, Codex, Aider, and any other AI tool) working in this repository. + +## Start here + +Whatever you do, start by reading entire [DEV_DOCS.md](DEV_DOCS.md). Only then proceed to your task. + +## Other important resources + +- the repository [README.md](README.md) — high-level project description and quick install/usage +- the markdown files in [`docs/guide/`](docs/guide/) — user-facing guides (installation, configuration, built-in functions, custom functions, integrations, etc.) +- the markdown files in [`docs/api/`](docs/api/) — API reference (generated from JSDoc; run `npm run docs:build` if the folder is missing) + +Prefer reading these local files over fetching the rendered documentation from the web. + +## Response style + +- Be concise by default. Use as few words as possible unless the user asks for more detail. +- When the user asks for specific content, lead the response with the requested information. +- Structure answers with bullet lists, numbered lists, tables, or code blocks where useful. +- Ask clarifying questions when the request is ambiguous rather than guessing. +- If you do not know something, say so and ask for help. +- When answering from project documentation, quote the exact relevant fragments to support your claim. + +## Common ways agents fail + +This section is maintained by the team. Whenever an AI agent makes a mistake worth flagging, an item is added here describing what the agent did wrong and what it should have done instead. Read this list before starting any non-trivial task. + + + +_No items yet._ + +## Skills, MCPs, and other agent tools + +This section is maintained by the team. Skills, MCP servers, and other tools vetted as useful for AI agents working on this codebase are listed here. + + + +_No items yet._ diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 5a11d26cd..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,95 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -HyperFormula is a headless spreadsheet engine written in TypeScript. It parses and evaluates Excel-compatible formulas and can run in browser or Node.js environments. The library implements ~400 built-in functions with support for custom functions, undo/redo, CRUD operations, and i18n (17 languages). - -## Build & Development Commands - -```bash -npm install # Install dependencies -npm run compile # TypeScript compilation to lib/ -npm run bundle-all # Full build: compile + bundle all formats -npm run lint # Run ESLint -npm run lint:fix # Auto-fix lint issues -``` - -## Testing - -```bash -npm test # Full suite: lint + unit + browser + compatibility -npm run test:unit # Jest unit tests only -npm run test:watch # Jest watch mode (run tests on file changes) -npm run test:coverage # Unit tests with coverage report -npm run test:browser # Karma browser tests (Chrome/Firefox) -npm run test:performance # Run performance benchmarks -npm run test:compatibility # Excel compatibility tests -``` - -Test files are located in `test/unit/` and follow the pattern `*.spec.ts`. - -## Architecture - -### Core Components - -- **`src/HyperFormula.ts`** - Main engine class, public API entry point -- **`src/parser/`** - Formula parsing using Chevrotain parser generator -- **`src/interpreter/`** - Formula evaluation engine -- **`src/DependencyGraph/`** - Cell dependency tracking and recalculation order -- **`src/CrudOperations.ts`** - Create/Read/Update/Delete operations on sheets and cells - -### Function Plugins (`src/interpreter/plugin/`) - -All spreadsheet functions are implemented as plugins extending `FunctionPlugin`. Each plugin: -- Declares `implementedFunctions` static property mapping function names to metadata -- Uses `runFunction()` helper for argument validation, coercion, and array handling -- Registers function translations in `src/i18n/languages/` - -To add a new function: -1. Create or modify a plugin in `src/interpreter/plugin/` -2. Add function metadata to `implementedFunctions` -3. Implement the function method -4. Add translations to all language files in `src/i18n/languages/` -5. Add tests in `test/unit/interpreter/` - -### i18n (`src/i18n/languages/`) - -Function name translations for each supported language. When adding new functions, translations can be found at: -- https://support.microsoft.com/en-us/office/excel-functions-translator-f262d0c0-991c-485b-89b6-32cc8d326889 -- http://dolf.trieschnigg.nl/excel/index.php - -## Output Formats - -The build produces multiple output formats: -- `commonjs/` - CommonJS modules (main entry) -- `es/` - ES modules (.mjs files) -- `dist/` - UMD bundles for browsers -- `typings/` - TypeScript declaration files - -## Contributing Guidelines - -- Create feature branches, never commit directly to master -- Target the `develop` branch for pull requests -- Add tests for all changes in `test/` folder -- Run linter before submitting (`npm run lint`) -- Maintain compatibility with Excel and Google Sheets behavior -- In documentation, commit messages, pull request descriptions and code comments, do not mention Claude Code nor LLM models used for code generation - -## Response Guidelines - -- By default speak ultra-concisely, using as few words as you can, unless asked otherwise. -- Focus solely on instructions and provide relevant responses. -- Ask questions to remove ambiguity and make sure you're speaking about the right thing. -- Ask questions if you need more information to provide an accurate answer. -- If you don't know something, simply say, "I don't know," and ask for help. -- Present your answer in a structured way, use bullet lists, numbered lists, tables, etc. -- When asked for specific content, start the response with the requested info immediately. -- When answering based on context, support your claims by quoting exact fragments of available documents. - -## Code Style - -- When generating code, prefer functional approach whenever possible (in JS/TS use filter, map and reduce functions). -- Make the code self-documenting. Use meaningfull names for classes, functions, valiables etc. Add code comments only when necessary. -- Add jsdocs to all classes and functions. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index d3f946c21..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,47 +0,0 @@ -# Contributing - -You are welcome to contribute to HyperFormula development. Your help -is much appreciated in any of the following topics: - -* Making pull requests - * Adding new functions - * Adding new features - * Improving the quality of the existing code - * Improving performance - * Improving documentation and public API -* Reporting bugs -* Suggesting improvements -* Suggesting new features - -## Good first issue - -Adding a new function will be a huge help for the library growth and -should not be too problematic for the first issue. Extending the -library of translations is also a good task to start with. -[Here](https://docs.google.com/spreadsheets/d/1UUskn4ZDDjLGSpO6kg73DOvabNoeqLbkJYyVfLyYlYw) -you can find a list of functions' translations. - -Visit [building]( https://handsontable.com/docs/hyperformula/guide/building.html) section to -get more info about the development process and check the list of commands you -can run in this project. Check the `/i18n` -folder in the project - all translations are kept just right there. -For the functions see the `interpreter/plugin` folder. Both of them -are a good starting point. - -## How to get started - -1. First, sign this -[Contributor License Agreement](https://goo.gl/forms/yuutGuN0RjsikVpM2) -to allow us to use and publish your changes. -2. Always make your changes on a separate branch. This will speed up -the merging process. -3. Always make the target of your pull request the `develop` branch, -not `master`. -4. For any change you make, add test specs in the `test` folder. -5. Please lint the code. See the section about using linter. -6. Add a comprehensive description of all the changes. - -## Code of conduct - -By participating in this project, you are expected to uphold our -[Code of Conduct](https://github.com/handsontable/hyperformula/blob/master/CODE_OF_CONDUCT.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 120000 index 000000000..6c263eead --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +docs/guide/contributing.md \ No newline at end of file diff --git a/DEV_DOCS.md b/DEV_DOCS.md index aede9c347..24461cf36 100644 --- a/DEV_DOCS.md +++ b/DEV_DOCS.md @@ -1,27 +1,104 @@ -# Dev Docs +# Developer documentation -Random notes and things to know useful for maintainers and contributors. +Canonical reference for everyone working on the HyperFormula source code: maintainers, the internal team, and AI agents triggered by them. Everything a developer needs to know lives here or is linked from here. -## Definition of Done for the code changes +## Quick links -Each change to the production code (bugfixes, new features, improvements) must include these elements. They must be present in the pull request BEFORE requesting the code review. +- **[Building, testing, and linting](docs/guide/building.md)** — all `npm` commands and build outputs +- **[Test suite](test/README.md)** — smoke tests and how to attach the private test suite +- **[Public docs portal](https://hyperformula.handsontable.com/docs)** — main documentation +- **[Docs README](docs/README.md)** — how to run the docs portal locally +- **[Changelog](CHANGELOG.md)** +- **[Pull request template](.github/pull_request_template.md)** -- changes to the production code - - including changes to all supported language packs in `src/i18n/languages` directory (if applicable) -- automatic tests - - for bugfixes: at least one test reproducing the bug - - for new features: a set of tests describing the feature specification precisely - - pull requests from external contributors should include tests in `tests/` directory (they will be moved to the private repository by the internal team) - - internal team adds tests directly to the private repository (through a separate pull request) -- updates to documentation related to the change +## Repository layout + +``` +. +├── src/ # Source code +│ ├── HyperFormula.ts # Main engine class, public API entry point +│ ├── parser/ # Formula parsing (uses Chevrotain parser generator) +│ ├── interpreter/ # Formula evaluation engine +│ │ └── plugin/ # Built-in spreadsheet function plugins +│ ├── DependencyGraph/ # Cell dependency tracking and recalculation order +│ ├── CrudOperations.ts # Create/read/update/delete operations on sheets and cells +│ └── i18n/ # Function-name translations per language +├── test/ # Test suite +├── docs/ # Public documentation portal (VuePress) +│ ├── guide/ # Markdown guides (building, contributing, usage…) +│ ├── api/ # API reference (generated from JSDoc) +│ ├── .vuepress/ # VuePress configuration, theme, components +│ └── README.md # How to run the docs portal locally +├── script/ # Maintenance and release scripts +├── .github/ # CI workflows, issue and PR templates +├── DEV_DOCS.md # Canonical developer documentation (this file) +├── AGENTS.md # Guidance for AI agents +├── CONTRIBUTING.md # Guide for external contributors +├── README.md # Project overview +├── CHANGELOG.md +├── LICENSE.txt +├── package.json +└── tsconfig.json +``` + +## Architecture + +### Core modules + +- `src/HyperFormula.ts` — main engine class, public API entry point +- `src/parser/` — formula parsing (uses the [Chevrotain](https://chevrotain.io/) parser generator) +- `src/interpreter/` — formula evaluation engine +- `src/DependencyGraph/` — cell dependency tracking and recalculation order +- `src/CrudOperations.ts` — create/read/update/delete operations on sheets and cells + +### Function plugins (`src/interpreter/plugin/`) + +All spreadsheet functions are implemented as plugins extending `FunctionPlugin`. Each plugin: + +- declares an `implementedFunctions` static property mapping function names to metadata +- uses the `runFunction()` helper for argument validation, coercion, and array handling +- registers function translations in `src/i18n/languages/` + +## How to add a new function + +Adding a built-in function is similar to adding a [custom function](docs/guide/custom-functions.md), so that guide is a useful reference for the function-implementation patterns (argument metadata, return types, array handling). The built-in flow on top of that is: + +1. Create or modify a plugin in `src/interpreter/plugin/`. +2. Add function metadata to `implementedFunctions`. +3. Implement the function method. +4. Add translations to all language files in `src/i18n/languages/`. +5. Add tests in `test/unit/interpreter/`. + +## Code style + +- Prefer a functional approach where possible (`filter`, `map`, `reduce`). +- Write self-documenting code: use meaningful names for classes, functions, and variables. Add code comments only when they explain intent the code itself cannot. +- Add JSDoc to all classes and functions. +- ESLint is the source of truth for formatting and code rules. Run `npm run lint` before submitting changes (see [building](docs/guide/building.md#run-the-linter)). + +## Definition of Done + +Each change to the production code (bugfix, new feature, or improvement) must include the following elements **before** requesting a code review: + +- Changes to the production code + - including changes to all supported language packs in `src/i18n/languages` (if applicable) +- Automatic tests + - for bug fixes: at least one test reproducing the bug + - for new features: a set of tests precisely describing the feature + - pull requests from external contributors should include tests in the `test/` directory (they will be moved to the private repository by the internal team) + - the internal team adds tests directly to the private repository (through a separate pull request) +- Updates to documentation related to the change - for breaking changes: a section in the migration guide -- technical documentation in the form of the jsdoc comments (high-level description of the concepts used in the more complex code fragments) -- changelog entry -- pull request description +- Technical documentation in the form of JSDoc comments (high-level description of the concepts used in more complex code fragments) +- Changelog entry +- Pull request description + +## Internationalization and function translations + +HyperFormula supports internationalization and provides localized function names for all built-in languages. Translation files live in `src/i18n/languages/`. New functions must include translations for all built-in languages. -## Sources of the function translations +When looking for the valid translations for new functions, try these sources: -HF supports internationalization and provides the localized function names for all built-in languages. When looking for the valid translations for the new functions, try these sources: - https://support.microsoft.com/en-us/office/excel-functions-translator-f262d0c0-991c-485b-89b6-32cc8d326889 - http://dolf.trieschnigg.nl/excel/index.php diff --git a/docs/guide/building.md b/docs/guide/building.md index 1e75be016..7d20b71a2 100644 --- a/docs/guide/building.md +++ b/docs/guide/building.md @@ -4,6 +4,21 @@ The build process uses Webpack and Babel, as well as npm tasks listed in package.json. During this process, the source located in the `src/*` directory is transformed into the output files. +The library is developed in TypeScript and the exact configuration +options can be found in `tsconfig.json`. To run the commands you need +to set up your environment to have `npm` or `yarn` properly installed. +After that, navigate to the project and run `npm install`. + +## Output formats + +The build produces the following output formats, all declared as +entry points in `package.json`: + +* `commonjs/` - CommonJS modules (main entry, used by Node.js and bundlers) +* `es/` - ES modules (`.mjs` files, used by tree-shaking bundlers) +* `dist/` - UMD bundles for direct use in the browser +* `typings/` - TypeScript declaration files (`.d.ts`) + **For UMD versions which reside in CDN:** * `./dist/hyperformula.js` - a full version which does not have @@ -14,16 +29,6 @@ have dependencies, they need to be added manually * `./dist/hyperformula.full.min.js` - a minified version with dependencies -There are also versions of builds in CommonJS, ES6, and TypeScript -definitions. They are marked in the package.json file. Based on -the tools used (Webpack, parsers, etc.), a proper build will be -respectively chosen. - -The library is developed in TypeScript and the exact configuration -options can be found in `tsconfig.json`. To run the commands you need -to set up your environment to have `npm` or `yarn` properly installed. -After that, navigate to the project and run `npm install`. - ## Build the project To build the project you can use the following commands: