git:20260727.108e017 to git:20260908.458f502
11 added, 4 removed. Audit A to A.
This is the Effect library repository, focusing on functional programming patterns and effect systems in TypeScript.
## Overview
- The git base branch is `main`.
- Use `pnpm` as the package manager.
- Keep changes focused and follow established patterns in the repository.
- Before writing code, read the relevant files in `./.patterns/` and inspect similar existing code.
## Think Before Coding
**Don't assume. Don't hide confusion. Surface tradeoffs.**
Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
## Simplicity First
**Minimum code that solves the problem. Nothing speculative.**
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
## Surgical Changes
**Touch only what you must. Clean up only your own mess.**
When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.
When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
The test: Every changed line should trace directly to the user's request.
## Goal-Driven Execution
**Define success criteria. Loop until verified.**
Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"
For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
## Workflow
1. Inspect nearby implementation, tests, and pattern docs before editing.
2. Prefer existing abstractions and conventions over introducing new ones.
3. For ad hoc runnable code, create a temporary file in `scratchpad/`, run it with `node scratchpad/<file>.ts`, and delete it when done.
The local runtime is Node 24, which can run TypeScript files directly; use plain `node` for local TypeScript probes instead of `tsx` unless `node` fails.
4. Run the validation appropriate to the change type.
5. Report which validation commands were run and any commands that could not be run.
## Validation
Use the narrowest validation that still covers the change:
| Change type | Validation |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| Code changes | `pnpm lint-fix`, targeted `pnpm test --run <test_file.ts>`, `pnpm check` |
| Tests-only changes | `pnpm lint-fix`, targeted `pnpm test --run <test_file.ts>`, `pnpm check` |
| Type-level/API type changes | Targeted `pnpm test-types <filename>`, plus `pnpm check` when source types changed |
| JSDoc text/category/link changes | `pnpm lint` |
- | JSDoc example changes | `pnpm lint`; from the changed package directory, run `pnpm docgen` |
+ | JSDoc example changes | `pnpm lint`; root `pnpm doctest --run <files>` |
| Docs-only changes | `pnpm lint-fix`; no tests required unless examples or code changed |
- Never run the whole test suite. A bare `pnpm test` runs every package in watch mode and will not
+ Never run the whole test suite. A bare `pnpm test` or `pnpm doctest` runs every package in watch mode and will not
exit; always pass `--run` and the specific test files covering your change. CI runs the full suite
on push, so leave that to CI.
## Bundle Size Preview
When asked to show bundle-size impact for a commit, use the existing bundle comparison workflow:
1. For the latest commit, run `pnpm bundle-compare HEAD~1`.
For another base, run `pnpm bundle-compare <base-ref>`.
2. Read the Markdown report from `tmp/bundle-stats.txt` and summarize the non-zero differences.
3. Leave `tmp/bundle-base` in place unless cleanup is requested. To clean it up, run `git worktree remove --force tmp/bundle-base`.
## Coding Patterns
Read `.patterns/effect.md` before changing Effect code. In particular:
- Prefer `Effect.fnUntraced` over functions that only return `Effect.gen`.
- Prefer class syntax for `Context.Service`.
- Do not use `async` / `await` or `try` / `catch`; use Effect APIs such as `Effect.gen`, `Effect.fnUntraced`, and `Effect.tryPromise`.
- Do not use `Date.now` or `new Date`; use `Clock`, and use `TestClock` in tests.
## Testing
Read `.patterns/testing.md` before writing or changing tests.
- Run only the tests covering the files you changed.
- From the repository root, run an affected package with `pnpm --filter effect test --run` only when package-wide coverage is necessary.
- Prefer a single test file, using a path relative to the package: `pnpm --filter effect test --run test/Option.test.ts`.
Replace the package name and test path with those covering your changed files, and narrow further with `-t "<test name>"` when useful.
- Test files are located in `packages/*/test/`.
- Main Effect library tests are in `packages/effect/test/`.
- Use `it.effect` for Effect-returning tests.
+ - `it.effect` and `it.live` already provide and close a `Scope` for each test; do not wrap test bodies in `Effect.scoped`.
- Use regular `it` for pure synchronous tests.
- Do not use `Effect.runSync` in tests.
- Do not use `expect` from Vitest; use `assert` from `@effect/vitest`.
- Type-level tests are in `packages/*/typetest/` and run with `pnpm test-types <filename>`.
## Documentation
- For AI documentation, read `ai-docs/README.md` very carefully before writing examples.
- AI documentation changes may include explanatory comments when useful.
- - For public JSDoc `@category` guidance, read `.patterns/jsdoc.md`.
- - When JSDoc examples are localized to a single package, run `pnpm docgen` from that package directory instead of the repository root.
+ - For public JSDoc categories and example best practices, read `.patterns/jsdoc.md`.
+ - Mark runnable TypeScript examples with `````ts import.meta.vitest``. Leave examples that register Vitest tests or suites
+ as plain `````ts`` fences because the doctest collector executes runnable snippets inside tests; invoke registration
+ APIs directly to show their intended top-level usage.
+ - Prefer direct trailing value assertions such as `operation() // => Option.some(1)`. Keep bindings only for reuse or meaningful multi-step setup, separate later assertion blocks with a blank line, use dense expected arrays such as `[1, 2]`, and keep a call on one line when the complete line is at most 120 characters.
+ - Assert semantic values rather than console formatting. Preserve `import.meta.vitest` on type-level examples without adding tautological runtime assertions.
+ - Keep marked examples self-contained, deterministic, bounded, and free of external-service dependencies. Await asynchronous work.
+ - Run `pnpm doctest --run <source files>` from the repository root to execute changed examples.
## Generated Files
Do not hand-edit generated files. Run the appropriate generator instead.
- `index.ts` barrel files are generated; run `pnpm codegen` after adding or removing modules.
## Changesets
Create a changeset in `.changeset/` for runtime behavior changes or exported type/API changes:
```md
---
"package-name": patch/minor/major
---
A description of the change.
```
Tests-only changes, internal refactors, docs-only changes, and JSDoc-only maintenance may skip changesets by maintainer decision.