| 1 | This is the Effect TypeScript monorepo. The git base branch is `main`; use `pnpm` from the repository root. |
| 2 | |
| 3 | ## Layout |
| 4 | |
| 5 | - Core library source, runtime tests, and type tests are in `packages/effect/src`, `packages/effect/test`, and |
| 6 | `packages/effect/typetest`. |
| 7 | - Other package families include `packages/ai`, `packages/atom`, `packages/platform`, `packages/sql`, and |
| 8 | `packages/tools`; standalone packages also live directly under `packages`. |
| 9 | - Package tests and type tests live beside source in `test` and `typetest` directories. |
| 10 | - AI documentation sources are in `ai-docs/src`. |
| 11 | - Changesets are in `.changeset`. |
| 12 | - Migration sources (v3-to-v4) are in `migration/annotations`. |
| 13 | - Inspect nearby code before editing. |
| 14 | |
| 15 | ## Validation |
| 16 | |
| 17 | Use the narrowest validation that covers the change: |
| 18 | |
| 19 | | Change type | Validation | |
| 20 | | ---------------------------------- | ---------------------------------------------------------------------------------- | |
| 21 | | Runtime source or test changes | `pnpm lint-fix`, targeted `pnpm test --run <test_file.ts>`, `pnpm check` | |
| 22 | | Type-system behavior or type tests | Targeted `pnpm test-types <filename>`, plus `pnpm check` when source types changed | |
| 23 | | JSDoc text/category/link changes | `pnpm jsdocs --check`, `pnpm lint` | |
| 24 | | JSDoc example changes | `pnpm jsdocs --check`, `pnpm lint`, root `pnpm doctest --run <files>` | |
| 25 | | Docs-only changes | `pnpm lint-fix`; no tests unless examples or code changed | |
| 26 | |
| 27 | Choose coverage from the contract being changed. Runtime tests cover executed |
| 28 | behavior. Tstyche tests cover intended compiler behavior such as inference, |
| 29 | assignability, rejection, or displayed public types. An ordinary source edit or |
| 30 | exported declaration is covered by `pnpm check` unless compiler behavior is part |
| 31 | of the task. |
| 32 | |
| 33 | Never run bare `pnpm test` or `pnpm doctest`; both start the full suite in watch mode. Always pass `--run` and the |
| 34 | specific files covering the change. CI runs the full suite. |
| 35 | |
| 36 | For an ad hoc runnable probe, create `scratchpad/<name>.ts`, run it with plain `node`, and remove it when finished. |
| 37 | |
| 38 | Report any commands that could not be run. |
| 39 | |
| 40 | ## Generated Files |
| 41 | |
| 42 | Do not edit generated output directly. |
| 43 | |
| 44 | Some `index.ts` sections marked with `@barrel` are generated. Do not edit those |
| 45 | sections manually; update their source modules and run `pnpm codegen`. |
| 46 | Hand-maintained `index.ts` files and unmarked sections are not covered by this |
| 47 | rule. |
| 48 | |
| 49 | `LLMS.md` is generated from `ai-docs/src`, and `migration/v3-to-v4.md` is |
| 50 | generated from `migration/annotations`. Update checked-in third-party assets |
| 51 | through their generator or documented import procedure. |