Merge develop (HF-65 in-repo dev docs cleanup) into docs/astro-migration

GreenFlux · GreenFlux · commit 8a2f793b016b · 2026-06-01T13:41:46.000-04:00
Brings in `00e5c730a` "Clean up in-repo dev docs (HF-65) (#1682)" which adds root-level `DEV_DOCS.md`, `AGENTS.md`, `.cursor/rules/main.mdc`, and re-points root `CLAUDE.md` / `CONTRIBUTING.md` as symlinks. Those files live at the repo root and govern library development, separate from the docs-site governance files this PR adds under `docs/` (`docs/CLAUDE.md`, `docs/AGENTS.md`, `docs/README-EDITING.md`, `docs/README-DEPLOYMENT.md`). Git's rename detection auto-applied develop's edits to `docs/guide/building.md` to the migrated location at `docs/src/content/docs/guide/building.md` — no conflicts.
diff --git a/.cursor/rules/main.mdc 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
@@ -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) &mdash; high-level project description and quick install/usage
+- the markdown files in [`docs/guide/`](docs/guide/) &mdash; user-facing guides (installation, configuration, built-in functions, custom functions, integrations, etc.)
+- the markdown files in [`docs/api/`](docs/api/) &mdash; 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.
+
+<!-- Add new items to the top of the list. Use the format:
+- **Short title** &mdash; What the agent did wrong. What it should have done instead.
+-->
+
+_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.
+
+<!-- Add new items here. Use the format:
+- **Name** &mdash; What it provides and when to use it.
+-->
+
+_No items yet._
diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1 @@
+docs/guide/contributing.md
diff --git 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)** &mdash; all `npm` commands and build outputs
+- **[Test suite](test/README.md)** &mdash; smoke tests and how to attach the private test suite
+- **[Public docs portal](https://hyperformula.handsontable.com/docs)** &mdash; main documentation
+- **[Docs README](docs/README.md)** &mdash; 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` &mdash; main engine class, public API entry point
+- `src/parser/` &mdash; formula parsing (uses the [Chevrotain](https://chevrotain.io/) parser generator)
+- `src/interpreter/` &mdash; formula evaluation engine
+- `src/DependencyGraph/` &mdash; cell dependency tracking and recalculation order
+- `src/CrudOperations.ts` &mdash; 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/src/content/docs/guide/building.md b/docs/src/content/docs/guide/building.md
@@ -7,6 +7,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
@@ -17,16 +32,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:
