|
| 1 | +# AGENTS |
| 2 | + |
| 3 | +Short rules for working in this repo. |
| 4 | + |
| 5 | +## Scope |
| 6 | + |
| 7 | +- This is a Go CLI project to inject environment variables into **bundled** javascript files. |
| 8 | +- All changes must be clean and testable. |
| 9 | + |
| 10 | +## Setup |
| 11 | + |
| 12 | +- See `magefile.go` for all available scripts |
| 13 | + |
| 14 | +```sh |
| 15 | +# setup |
| 16 | +mage -v bootstrap |
| 17 | +``` |
| 18 | + |
| 19 | +```sh |
| 20 | +# build single debug binary (current platform), outputs to root directory |
| 21 | +mage -v build:debug |
| 22 | +``` |
| 23 | + |
| 24 | +```sh |
| 25 | +# build all release binaries (cross platform), outputs to bin/ |
| 26 | +mage -v build:release |
| 27 | +``` |
| 28 | + |
| 29 | +```sh |
| 30 | +# bundles all binaries into zips, ready for release/distribution |
| 31 | +mage -v release |
| 32 | +``` |
| 33 | + |
| 34 | +## Structure |
| 35 | + |
| 36 | +- `bin/` output directory for binaries |
| 37 | +- `command/` package containing all CLI commands |
| 38 | +- `npm/` npm release directories |
| 39 | +- `reactenv/` core package for logic |
| 40 | +- `tools/` package for build tools. ensures tool dependencies are kept in sync |
| 41 | +- `ui/` package for terminal UI logic |
| 42 | +- `version/` package just for the version |
| 43 | + |
| 44 | +## Conventions |
| 45 | + |
| 46 | +- Add brief code comments for tricky or non-obvious logic. |
| 47 | + |
| 48 | +## Tests |
| 49 | + |
| 50 | +- Tests are written in `Vitest` |
| 51 | +- Everything should be tested, and be testable |
| 52 | +- New behavior requires tests (unit or e2e). |
| 53 | + |
| 54 | +### Test tips |
| 55 | + |
| 56 | +A few tips to write better tests: |
| 57 | + |
| 58 | +[Russ Cox - Go Testing By Example](https://www.youtube.com/watch?v=1-o-iJlL4ak) |
| 59 | + |
| 60 | +- Make it easy to add new tests. |
| 61 | +- Use test coverage to find untested code. |
| 62 | +- Coverage is no substitute for thought. |
| 63 | +- Write exhaustive tests. |
| 64 | +- Separate test cases from test logic (i.e use test case tables, separate from logic). |
| 65 | +- Look for special cases. |
| 66 | +- If you didn't add a test, you didn't fix the bug. |
| 67 | +- Test cases can be in testdata files. |
| 68 | +- Compare against other implementations. |
| 69 | +- Make test failures readable. |
| 70 | +- If the answers can change, wtite coed to update them. |
| 71 | +- Code quality is limited by test quality. |
| 72 | +- Scripts make good test cases. |
| 73 | +- Improve your tests over time. |
| 74 | + |
| 75 | +## Commits |
| 76 | + |
| 77 | +- Follow `CONTRIBUTING.md` prefix rules and lowercase messages. |
| 78 | + |
| 79 | +## Agent-Specific Notes |
| 80 | + |
| 81 | +- When answering questions, respond with high-confidence answers only: verify in code; do not guess. |
0 commit comments