|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Instructions for AI coding agents (Claude Code, Cursor, Codex, Copilot Workspace, etc.) opening pull requests against this repository. |
| 4 | + |
| 5 | +Human contributors: see [CONTRIBUTING.md](CONTRIBUTING.md). The rules below also apply to any human submitting AI-generated code. |
| 6 | + |
| 7 | +If you are an AI agent, read this file in full before making changes. The patterns below come from real PRs we have had to reject or rework. |
| 8 | + |
| 9 | +--- |
| 10 | + |
| 11 | +## Hard rules |
| 12 | + |
| 13 | +### 1. Surgical scope |
| 14 | + |
| 15 | +- Touch ONLY the lines required for the fix or feature. |
| 16 | +- Do NOT extract constants, rename variables, collapse `Promise.all`, rewrite `reduce` to `for`, or "clean up" surrounding code, even if your linter or style tool suggests it. |
| 17 | +- If the pre-commit hook (prettier ↔ eslint conflict) fights you, commit with `--no-verify` and call this out in the PR description. Do NOT reshape unrelated code to satisfy the hook. |
| 18 | + |
| 19 | +### 2. No formatter sweeps |
| 20 | + |
| 21 | +- Do NOT run `npx prettier --write .`, `eslint --fix` on whole files, or any tool that rewrites files you did not otherwise change. |
| 22 | +- Do NOT modify `.prettierrc`, `.eslintrc`, or other config files in a feature/bugfix PR. If a config change is needed, open a separate config-only PR. |
| 23 | + |
| 24 | +### 3. PR description must be complete |
| 25 | + |
| 26 | +- List EVERY file changed in the PR description, including configs, lockfiles, and incidental edits. |
| 27 | +- If you used `--no-verify`, say so and explain why. |
| 28 | +- If your change depends on or conflicts with another open PR, link it. |
| 29 | + |
| 30 | +### 4. Tests must use real fixtures, not synthetic models |
| 31 | + |
| 32 | +- For XLSX read/write fixes, your test MUST round-trip through `wb.xlsx.load(...)` and/or `wb.xlsx.writeBuffer(...)` against a real or minimal fixture file. |
| 33 | +- Do NOT build hand-rolled model objects and call internal serializers (e.g. `XLSX.reconcile`, individual xforms) directly. Synthetic-model tests can pass while the real load/write path still breaks. |
| 34 | +- Place fixture files under `spec/integration/data/` following existing naming. |
| 35 | + |
| 36 | +### 5. Cross-check open PRs before submitting |
| 37 | + |
| 38 | +- Before opening a PR, list the currently open PRs in this repo and verify your change does not touch the same files or overlap in scope. The maintainer has had three concurrent PRs all editing `.prettierrc` because none of them checked. |
| 39 | +- Run: `gh pr list --state open --limit 50 --json number,title,files` |
| 40 | + |
| 41 | +### 6. XLSX serialization changes must be Excel-verified |
| 42 | + |
| 43 | +If your change touches anything that writes XLSX (xforms, sheet/workbook serialization, pivot tables, charts, comments, conditional formatting): |
| 44 | + |
| 45 | +- Verify the output file actually opens in Excel without a "Repaired Records" warning, OR |
| 46 | +- Round-trip with LibreOffice headless and inspect the bytes: |
| 47 | + ```bash |
| 48 | + soffice --headless --convert-to xlsx /tmp/your-output.xlsx --outdir /tmp/roundtrip |
| 49 | + unzip -p /tmp/roundtrip/your-output.xlsx xl/<relevant-part>.xml | head |
| 50 | + ``` |
| 51 | +- Unit tests do NOT catch Excel's repair warnings. This step is mandatory for serialization-touching PRs. |
| 52 | + |
| 53 | +### 7. Dependency bumps require runtime smoke tests |
| 54 | + |
| 55 | +- Major-version dep bumps (e.g. `fast-csv`, `unzipper`, `archiver`) MUST be smoke-tested against the runtime paths that use them, not just `npm test`. |
| 56 | +- Streaming reader changes: load a real `.xlsx`. CSV writer changes: write and re-parse real CSV. Document the smoke test in the PR. |
| 57 | + |
| 58 | +### 8. One concern per PR |
| 59 | + |
| 60 | +- Bug fix + sibling bugs of the same shape in the same file: ONE PR. Good. |
| 61 | +- Bug fix + unrelated cleanup + dep bump: THREE PRs. Required. |
| 62 | +- If you find yourself touching `index.d.ts`, `README.md`, `package-lock.json`, etc. incidentally, stop and revert those edits unless they are the actual subject of the PR. |
| 63 | + |
| 64 | +--- |
| 65 | + |
| 66 | +## Per-PR checklist (also in `.github/pull_request_template.md`) |
| 67 | + |
| 68 | +Before opening the PR, verify: |
| 69 | + |
| 70 | +- [ ] Only the lines required for the fix are changed |
| 71 | +- [ ] No prettier/eslint sweeps on unrelated files |
| 72 | +- [ ] Every file change is listed in the PR description below |
| 73 | +- [ ] Tests use real fixture round-trip (`wb.xlsx.load` / `writeBuffer`), not synthetic models |
| 74 | +- [ ] `gh pr list --state open` checked for conflicting PRs |
| 75 | +- [ ] (If serialization) Output file opens in Excel or `soffice --headless` without warnings |
| 76 | +- [ ] (If `--no-verify` used) Reason noted in PR description |
| 77 | +- [ ] (If dep bump) Runtime smoke test described in PR |
| 78 | + |
| 79 | +--- |
| 80 | + |
| 81 | +## Repository conventions |
| 82 | + |
| 83 | +- Code style: enforced by ESLint + Prettier (the conflict above is real — live with it on a per-PR basis) |
| 84 | +- Tests: Mocha, in `spec/unit/`, `spec/integration/`, `spec/end-to-end/` |
| 85 | +- Run unit tests fast: `npm run test:unit` (skips the build step) |
| 86 | +- Full suite: `npm test` (build + unit + integration + e2e + jasmine) |
| 87 | +- Node target: see `engines` in `package.json` |
| 88 | +- Browserify is in the build chain. Do NOT introduce dependencies that ship ES2021+ syntax (`??=`, `?.()`) in their CJS output, or that publish `exports`-only packages without a `main` field. Both break the browser bundle. |
| 89 | + |
| 90 | +--- |
| 91 | + |
| 92 | +## What this fork is |
| 93 | + |
| 94 | +This is a curated Protobi fork of [exceljs/exceljs](https://github.com/exceljs/exceljs). We selectively adopt upstream features for production use. We are NOT a general-purpose alternative fork. See [CONTRIBUTING.md](CONTRIBUTING.md) for what we accept. |
| 95 | + |
| 96 | +If your change is a generic improvement that has not been merged upstream, consider opening it against [exceljs/exceljs](https://github.com/exceljs/exceljs) first. |
0 commit comments