From 116fafbebfb5581e324d6cab1ce0b73cb28901f6 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 13:11:12 +0000 Subject: [PATCH 01/15] docs(building): document output formats and reorder intro Co-authored-by: Kuba Sekowski --- docs/guide/building.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) 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: From c923d10d918234498d51fc87cf95aee983961f0d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 13:11:20 +0000 Subject: [PATCH 02/15] docs(dev): consolidate dev knowledge into DEV_DOCS.md Make DEV_DOCS.md the canonical reference for everyone working on the source code. It now contains: - quick links to building, contributing, code of conduct, tests, etc. - project overview - architecture (core modules, function plugins, i18n) - how to add a new function - code style - definition of done - sources of function translations Existing content (definition of done, translation sources) is preserved and grouped with the new sections so that information is no longer duplicated across CLAUDE.md and other files. Co-authored-by: Kuba Sekowski --- DEV_DOCS.md | 85 +++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 69 insertions(+), 16 deletions(-) diff --git a/DEV_DOCS.md b/DEV_DOCS.md index aede9c347..1dedc85bc 100644 --- a/DEV_DOCS.md +++ b/DEV_DOCS.md @@ -1,27 +1,80 @@ -# 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, external contributors, and AI agents. 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 +- **[Contributing guide](docs/guide/contributing.md)** — how to submit a pull request +- **[Code of conduct](docs/guide/code-of-conduct.md)** +- **[Test suite](test/README.md)** — smoke tests and how to attach the private test suite +- **[Public docs portal](https://hyperformula.handsontable.com/)** — end-user documentation +- **[Public docs source](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 +## Project overview + +HyperFormula is a headless spreadsheet engine written in TypeScript. It parses and evaluates Excel-compatible formulas and runs in both browser and Node.js environments. The library implements ~400 built-in functions with support for custom functions, undo/redo, CRUD operations, and i18n (17 languages). + +## 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/` + +### i18n (`src/i18n/languages/`) + +Function-name translations for each supported language. New functions must include translations for all built-in languages. See [Sources of the function translations](#sources-of-the-function-translations). + +## How 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/`. + +## 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 ## Sources of the function translations -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: +HyperFormula supports internationalization and provides localized function names for all built-in languages. When looking for the valid translations for 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 From 4e90faf2befbf365f59ff7d5a15221ee2eb39b4e Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 13:11:27 +0000 Subject: [PATCH 03/15] docs(agents): add AGENTS.md as single source for AI agent rules - AGENTS.md links to DEV_DOCS.md and adds rules that are specific to AI agents (attribution, response style). - CLAUDE.md is reduced to a pointer to AGENTS.md. - .cursor/rules/main.mdc is added so Cursor agents are routed to AGENTS.md as well. This removes the duplication that previously existed between CLAUDE.md and DEV_DOCS.md / docs/guide/building.md / docs/guide/contributing.md. Co-authored-by: Kuba Sekowski --- .cursor/rules/main.mdc | 6 +++ AGENTS.md | 28 +++++++++++++ CLAUDE.md | 94 +----------------------------------------- 3 files changed, 35 insertions(+), 93 deletions(-) create mode 100644 .cursor/rules/main.mdc create mode 100644 AGENTS.md 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..92b9d5a8c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,28 @@ +# AGENTS.md + +Instructions for AI coding agents (Cursor, Claude Code, Codex, Aider, and any other AI tool) working in this repository. + +## Start here + +All project knowledge a developer needs — project overview, architecture, build and test commands, code style, definition of done, how to add a function, and more — lives in **[DEV_DOCS.md](DEV_DOCS.md)**. Read it first. Everything in `DEV_DOCS.md` applies to AI agents as well. + +## Agent-only rules + +The rules below are intended for AI agents specifically and are not part of the standard developer documentation. + +### Communication and attribution + +- Do **not** mention Claude, Claude Code, Cursor, GPT, Codex, Copilot, or any other LLM/AI tool in: + - commit messages + - pull request titles or descriptions + - source code or code comments + - documentation (including the changelog) + +### 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. diff --git a/CLAUDE.md b/CLAUDE.md index 5a11d26cd..a263c7059 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,95 +1,3 @@ # 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. +See [AGENTS.md](AGENTS.md). From d66c50752b63ad7f2dfe5aefe5505146f81ba4a7 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 13:11:33 +0000 Subject: [PATCH 04/15] docs(contributing): replace duplicate file with pointer CONTRIBUTING.md duplicated docs/guide/contributing.md almost verbatim. Reduce it to a single link so that the docs portal version is the canonical source. Co-authored-by: Kuba Sekowski --- CONTRIBUTING.md | 46 +--------------------------------------------- 1 file changed, 1 insertion(+), 45 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3f946c21..149de0624 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,47 +1,3 @@ # 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). +See the [Contributing guide](docs/guide/contributing.md). From 320fa0a0f8a83617a6d7fb5609678b5f79df5a4a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 13:39:19 +0000 Subject: [PATCH 05/15] docs(agents): drop attribution rule, point to README/docs, add failure log Address PR review: - Remove the 'Communication and attribution' rule. - Update 'Start here' to point readers at the repository README and the public documentation portal in addition to DEV_DOCS.md. - Add a 'Common ways agents fail' section. The team will append items to it whenever an agent makes a mistake worth flagging, so future agents read it before starting non-trivial tasks. Co-authored-by: Kuba Sekowski --- AGENTS.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 92b9d5a8c..60c922680 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,21 +4,14 @@ Instructions for AI coding agents (Cursor, Claude Code, Codex, Aider, and any ot ## Start here -All project knowledge a developer needs — project overview, architecture, build and test commands, code style, definition of done, how to add a function, and more — lives in **[DEV_DOCS.md](DEV_DOCS.md)**. Read it first. Everything in `DEV_DOCS.md` applies to AI agents as well. +All project knowledge a developer needs — project overview, architecture, build and test commands, code style, definition of done, how to add a function, and more — lives in **[DEV_DOCS.md](DEV_DOCS.md)**. Start there. Everything in `DEV_DOCS.md` applies to AI agents as well. -## Agent-only rules +For additional context, also consult: -The rules below are intended for AI agents specifically and are not part of the standard developer documentation. +- the repository [README.md](README.md) — high-level project description and quick install/usage +- the public [documentation portal](https://hyperformula.handsontable.com/docs) — full end-user documentation -### Communication and attribution - -- Do **not** mention Claude, Claude Code, Cursor, GPT, Codex, Copilot, or any other LLM/AI tool in: - - commit messages - - pull request titles or descriptions - - source code or code comments - - documentation (including the changelog) - -### Response style +## 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. @@ -26,3 +19,13 @@ The rules below are intended for AI agents specifically and are not part of the - 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._ From 79b6d2236478ee947754c9ed4095249c2d32631d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 13:39:25 +0000 Subject: [PATCH 06/15] docs(dev): add repo tree, scope to internal team, fold i18n notes Address PR review: - Reframe the audience: maintainers, internal team, and AI agents triggered by them. Drop the contributing-guide link from the quick links since that document targets external contributors. - Update the public docs portal URL to the canonical /docs path. - Add a repository directory tree so people can navigate the repository quickly. - Drop the redundant 'Project overview' section. - Fold the architecture i18n subsection into the function-translations section so all i18n information lives in one place. Co-authored-by: Kuba Sekowski --- DEV_DOCS.md | 55 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 12 deletions(-) diff --git a/DEV_DOCS.md b/DEV_DOCS.md index 1dedc85bc..f424ace5b 100644 --- a/DEV_DOCS.md +++ b/DEV_DOCS.md @@ -1,21 +1,54 @@ # Developer documentation -Canonical reference for everyone working on the HyperFormula source code: maintainers, external contributors, and AI agents. Everything a developer needs to know lives here or is linked from here. +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. ## Quick links - **[Building, testing, and linting](docs/guide/building.md)** — all `npm` commands and build outputs -- **[Contributing guide](docs/guide/contributing.md)** — how to submit a pull request - **[Code of conduct](docs/guide/code-of-conduct.md)** - **[Test suite](test/README.md)** — smoke tests and how to attach the private test suite -- **[Public docs portal](https://hyperformula.handsontable.com/)** — end-user documentation +- **[Public docs portal](https://hyperformula.handsontable.com/docs)** — end-user documentation - **[Public docs source](docs/README.md)** — how to run the docs portal locally - **[Changelog](CHANGELOG.md)** - **[Pull request template](.github/pull_request_template.md)** -## Project overview - -HyperFormula is a headless spreadsheet engine written in TypeScript. It parses and evaluates Excel-compatible formulas and runs in both browser and Node.js environments. The library implements ~400 built-in functions with support for custom functions, undo/redo, CRUD operations, and i18n (17 languages). +## Repository layout + +```text +. +├── 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/ +│ └── languages/ # Function-name translations per language +├── test/ # Smoke tests + hook for the private test suite +│ ├── smoke.spec.ts +│ ├── fetch-tests.sh # Pulls the private hyperformula-tests repo +│ └── README.md # How the test suite is organized +├── 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 +├── examples/ # Runnable usage examples +├── script/ # Maintenance and release scripts +├── .github/ # CI workflows, issue and PR templates +├── .cursor/rules/ # Cursor agent rules (point to AGENTS.md) +├── DEV_DOCS.md # Canonical developer documentation (this file) +├── AGENTS.md # Guidance for AI agents +├── CLAUDE.md # → AGENTS.md (symlink) +├── CONTRIBUTING.md # → docs/guide/contributing.md (symlink) +├── README.md # Project overview for end users +├── CHANGELOG.md +├── CODE_OF_CONDUCT.md +├── LICENSE.txt +├── package.json +└── tsconfig.json +``` ## Architecture @@ -35,10 +68,6 @@ All spreadsheet functions are implemented as plugins extending `FunctionPlugin`. - uses the `runFunction()` helper for argument validation, coercion, and array handling - registers function translations in `src/i18n/languages/` -### i18n (`src/i18n/languages/`) - -Function-name translations for each supported language. New functions must include translations for all built-in languages. See [Sources of the function translations](#sources-of-the-function-translations). - ## How to add a new function 1. Create or modify a plugin in `src/interpreter/plugin/`. @@ -71,9 +100,11 @@ Each change to the production code (bugfix, new feature, or improvement) must in - Changelog entry - Pull request description -## Sources of the function translations +## 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. -HyperFormula supports internationalization and provides localized function names for all built-in languages. When looking for the valid translations for new functions, try these sources: +When looking for the valid translations for 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 From 8e46e40836b1744b918d72901e6a03bbd460d355 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 13:39:32 +0000 Subject: [PATCH 07/15] docs: replace CLAUDE.md and CONTRIBUTING.md pointer files with symlinks Address PR review: instead of one-line pointer files, make them filesystem symlinks so any tool that opens them sees the target content directly: - CLAUDE.md -> AGENTS.md - CONTRIBUTING.md -> docs/guide/contributing.md Co-authored-by: Kuba Sekowski --- CLAUDE.md | 4 +--- CONTRIBUTING.md | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) mode change 100644 => 120000 CLAUDE.md mode change 100644 => 120000 CONTRIBUTING.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index a263c7059..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,3 +0,0 @@ -# CLAUDE.md - -See [AGENTS.md](AGENTS.md). 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 149de0624..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,3 +0,0 @@ -# Contributing - -See the [Contributing guide](docs/guide/contributing.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 From b72d7a3a67a3f82837c16caa284b8a19e77eb0cf Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 13:54:04 +0000 Subject: [PATCH 08/15] docs: tighten dev-doc wording and trim repository tree Address PR review: - DEV_DOCS.md and AGENTS.md: describe the public portal as 'main documentation' (per reviewer suggestion). - DEV_DOCS.md: drop the Code of conduct link from quick links. - DEV_DOCS.md: collapse the test/ subtree, and remove tree entries for examples/, .cursor/rules/, CLAUDE.md, and CODE_OF_CONDUCT.md so the layout focuses on navigation-relevant directories. - DEV_DOCS.md: simplify the README.md description to 'Project overview'. Co-authored-by: Kuba Sekowski --- AGENTS.md | 2 +- DEV_DOCS.md | 14 +++----------- 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 60c922680..88deab3ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ All project knowledge a developer needs — project overview, architecture, For additional context, also consult: - the repository [README.md](README.md) — high-level project description and quick install/usage -- the public [documentation portal](https://hyperformula.handsontable.com/docs) — full end-user documentation +- the public [documentation portal](https://hyperformula.handsontable.com/docs) — main documentation ## Response style diff --git a/DEV_DOCS.md b/DEV_DOCS.md index f424ace5b..c991e425c 100644 --- a/DEV_DOCS.md +++ b/DEV_DOCS.md @@ -5,9 +5,8 @@ Canonical reference for everyone working on the HyperFormula source code: mainta ## Quick links - **[Building, testing, and linting](docs/guide/building.md)** — all `npm` commands and build outputs -- **[Code of conduct](docs/guide/code-of-conduct.md)** - **[Test suite](test/README.md)** — smoke tests and how to attach the private test suite -- **[Public docs portal](https://hyperformula.handsontable.com/docs)** — end-user documentation +- **[Public docs portal](https://hyperformula.handsontable.com/docs)** — main documentation - **[Public docs source](docs/README.md)** — how to run the docs portal locally - **[Changelog](CHANGELOG.md)** - **[Pull request template](.github/pull_request_template.md)** @@ -25,26 +24,19 @@ Canonical reference for everyone working on the HyperFormula source code: mainta │ ├── CrudOperations.ts # Create/read/update/delete operations on sheets and cells │ └── i18n/ │ └── languages/ # Function-name translations per language -├── test/ # Smoke tests + hook for the private test suite -│ ├── smoke.spec.ts -│ ├── fetch-tests.sh # Pulls the private hyperformula-tests repo -│ └── README.md # How the test suite is organized +├── 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 -├── examples/ # Runnable usage examples ├── script/ # Maintenance and release scripts ├── .github/ # CI workflows, issue and PR templates -├── .cursor/rules/ # Cursor agent rules (point to AGENTS.md) ├── DEV_DOCS.md # Canonical developer documentation (this file) ├── AGENTS.md # Guidance for AI agents -├── CLAUDE.md # → AGENTS.md (symlink) ├── CONTRIBUTING.md # → docs/guide/contributing.md (symlink) -├── README.md # Project overview for end users +├── README.md # Project overview ├── CHANGELOG.md -├── CODE_OF_CONDUCT.md ├── LICENSE.txt ├── package.json └── tsconfig.json From bbfc783fff2cbac216f319553ab640ab33ac3b5f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 14:00:27 +0000 Subject: [PATCH 09/15] ci: retrigger build (flaky failure on Node 24 + Windows + npm ci) The previous run failed only on the build (24, windows-latest, ci) matrix slot in 19s with no npm output captured. All other 17 matrix combinations passed, the same slot passed on the previous commit of this branch (f922598aa), and this branch only touches markdown files, so the failure is unrelated to the changes. Co-authored-by: Kuba Sekowski From 889ce6057c4f63203d3533472a217b8aa19b692c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 14:10:50 +0000 Subject: [PATCH 10/15] docs(dev): collapse i18n tree and clarify CONTRIBUTING.md role Address PR review: - Collapse src/i18n/ and src/i18n/languages/ into a single tree entry per reviewer suggestion. - Describe CONTRIBUTING.md as 'Guide for external contributors' instead of leaking the symlink target. Co-authored-by: Kuba Sekowski --- DEV_DOCS.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/DEV_DOCS.md b/DEV_DOCS.md index c991e425c..8d09dc369 100644 --- a/DEV_DOCS.md +++ b/DEV_DOCS.md @@ -22,8 +22,7 @@ Canonical reference for everyone working on the HyperFormula source code: mainta │ │ └── 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/ -│ └── languages/ # Function-name translations per language +│ └── i18n/ # Function-name translations per language ├── test/ # Test suite ├── docs/ # Public documentation portal (VuePress) │ ├── guide/ # Markdown guides (building, contributing, usage…) @@ -34,7 +33,7 @@ Canonical reference for everyone working on the HyperFormula source code: mainta ├── .github/ # CI workflows, issue and PR templates ├── DEV_DOCS.md # Canonical developer documentation (this file) ├── AGENTS.md # Guidance for AI agents -├── CONTRIBUTING.md # → docs/guide/contributing.md (symlink) +├── CONTRIBUTING.md # Guide for external contributors ├── README.md # Project overview ├── CHANGELOG.md ├── LICENSE.txt From ccf20442943459ec69887220109b4238cf8373a0 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 14:10:56 +0000 Subject: [PATCH 11/15] docs(agents): point agents at local docs/guide and docs/api markdown Address PR review: replace the link to the rendered documentation portal with pointers to the markdown sources in docs/guide/ and docs/api/, so agents read local files rather than fetching from the web. Note that docs/api/ is generated from JSDoc and requires running npm run docs:build if it is missing. Co-authored-by: Kuba Sekowski --- AGENTS.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 88deab3ef..d558e7ffc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,10 @@ All project knowledge a developer needs — project overview, architecture, For additional context, also consult: - the repository [README.md](README.md) — high-level project description and quick install/usage -- the public [documentation portal](https://hyperformula.handsontable.com/docs) — main documentation +- 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 From fd708d5bec1888dd10a04dbdf882e43e8340b07a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 14:19:50 +0000 Subject: [PATCH 12/15] docs(agents): tighten 'Start here' and rename resources section Per reviewer suggestions: - Replace the long 'Start here' paragraph with a direct one-sentence instruction to read DEV_DOCS.md first. - Promote 'For additional context, also consult:' to a proper 'Other important resources' heading. Co-authored-by: Kuba Sekowski --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d558e7ffc..82eaaceca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,9 +4,9 @@ Instructions for AI coding agents (Cursor, Claude Code, Codex, Aider, and any ot ## Start here -All project knowledge a developer needs — project overview, architecture, build and test commands, code style, definition of done, how to add a function, and more — lives in **[DEV_DOCS.md](DEV_DOCS.md)**. Start there. Everything in `DEV_DOCS.md` applies to AI agents as well. +Whatever you do, start by reading entire [DEV_DOCS.md](DEV_DOCS.md). Only then proceed to your task. -For additional context, also consult: +## 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.) From f19be5bcf7ed523fa21d8692687f7ecd9c2e0e3b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 14:19:56 +0000 Subject: [PATCH 13/15] docs(dev): rename Docs README link and reference custom-functions guide Per reviewer suggestions: - Rename the 'Public docs source' quick link to 'Docs README'. - In 'How to add a new function', point readers at docs/guide/custom-functions.md because adding a built-in function follows the same function-implementation patterns as adding a custom function. Co-authored-by: Kuba Sekowski --- DEV_DOCS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/DEV_DOCS.md b/DEV_DOCS.md index 8d09dc369..4155f9096 100644 --- a/DEV_DOCS.md +++ b/DEV_DOCS.md @@ -7,7 +7,7 @@ Canonical reference for everyone working on the HyperFormula source code: mainta - **[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 -- **[Public docs source](docs/README.md)** — how to run the docs portal locally +- **[Docs README](docs/README.md)** — how to run the docs portal locally - **[Changelog](CHANGELOG.md)** - **[Pull request template](.github/pull_request_template.md)** @@ -61,6 +61,8 @@ All spreadsheet functions are implemented as plugins extending `FunctionPlugin`. ## 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. From 36a0b6f844cfadecd7a7d6aab5bfe18ff3831f33 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 26 May 2026 09:58:06 +0000 Subject: [PATCH 14/15] docs(agents): add maintained section for skills, MCPs, and agent tools Add an empty 'Skills, MCPs, and other agent tools' section that mirrors the 'Common ways agents fail' section so the team can list any skills, MCP servers, or other tools vetted as useful for agents working on this codebase. Co-authored-by: Kuba Sekowski --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 82eaaceca..ee5b0ee7d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,3 +32,13 @@ This section is maintained by the team. Whenever an AI agent makes a mistake wor --> _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._ From df801c87d1227be965e1dfccf5e6c6177469f557 Mon Sep 17 00:00:00 2001 From: marcin-kordas-hoc Date: Thu, 28 May 2026 10:10:58 +0000 Subject: [PATCH 15/15] fix(docs): add missing quick links + LLM no-mention rule + fix fence tag - DEV_DOCS.md: add contributing guide and code of conduct to Quick links (PR description claimed they were linked; they weren't) - DEV_DOCS.md: change unsupported \`\`\`text fence to \`\`\` (VuePress 1) - AGENTS.md: add LLM no-mention rule carried over from old CLAUDE.md ("do not mention AI tool names in commits, PRs, comments, docs") --- AGENTS.md | 1 + DEV_DOCS.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ee5b0ee7d..3dd0f918d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ Prefer reading these local files over fetching the rendered documentation from t - 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. +- In commit messages, PR descriptions, code comments, and documentation: do not mention the names of AI tools used for code generation. ## Common ways agents fail diff --git a/DEV_DOCS.md b/DEV_DOCS.md index 4155f9096..24461cf36 100644 --- a/DEV_DOCS.md +++ b/DEV_DOCS.md @@ -13,7 +13,7 @@ Canonical reference for everyone working on the HyperFormula source code: mainta ## Repository layout -```text +``` . ├── src/ # Source code │ ├── HyperFormula.ts # Main engine class, public API entry point