Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

- **Versions live only in the `pnpm-workspace.yaml` catalog** (`catalogMode: strict`; peer ranges under `catalogs.peers`). After editing it, run `pnpm install` and commit `pnpm-lock.yaml` — a stale lockfile fails CI with `ERR_PNPM_LOCKFILE_CONFIG_MISMATCH`.
- **`@effect/tsgo`, `@typescript/native` and `vite-plus` bump as a set** — read the comment on `@effect/tsgo` in `pnpm-workspace.yaml` first; an unsupported pairing fails `pnpm install` (the `prepare` script's `effect-tsgo patch` hard-errors).
- **The type checker of record is TypeScript 7** (`tsc`, the native compiler, via `vp run check`). It anchors a failed overload at the _properties_ that fail against the last overload rather than at the one the TS6 checker elaborated, which is why the `@ts-expect-error` markers on effect's `ErrorNoStream` guard in `src/Endpoint.ts` sit on `params:` / `query:` lines as well as `error:`. TS6 (`tsc6`, the JS compiler) is only what the JS-API consumers — `@effect/docgen`, the tsdown declaration bundler, the editor language service — load.
- **The type checker of record is TypeScript 7** (`tsc`, the native compiler, via `vp run check`). It anchors a failed overload at the _properties_ that fail against the last overload rather than at the one the TS6 checker elaborated, which is why the `@ts-expect-error` markers on effect's `ErrorNoStream` guard in `src/Endpoint.ts` sit on `params:` / `query:` lines as well as `error:`. TS6 (`tsc6`, the JS compiler) is only what the JS-API consumers — `@effect/docgen`'s parse, the tsdown declaration bundler, the editor language service — load.
- **`vp lint` runs the full Effect preset with a staged rollout.** The `warn` tier in `vite.config.ts` is debt, not headroom: fix any new site, and when a rule's count reaches zero flip it to `error` and delete its line. `@ts-expect-error` is the assertion mechanism of `test/*.types.ts` and stays allowed there.
- **`dist/` is bundled, not transpiled.** `vp pack` (tsdown) emits one ESM bundle per entry point (`.`, `./schema`) plus bundled declarations. `test/entry-points.test.ts` walks the built graph, and `test/emitted/requirements.types.ts` type-checks against the emitted `.d.ts` — both because what consumers see is not what `src/` resolves to.

Expand All @@ -20,7 +20,7 @@

### `vp run docgen` executes your examples

`@effect/docgen` doesn't just type-check JSDoc `@example` blocks — it **compiles them as ESM and runs them** (`vp run docgen`). Note this is a separate command/CI step from `vp check` + `vp run check` + `vp run -r test:unit` — those passing does not mean your examples run; run `docgen` too before you're done. A broken example fails the build, not a lint warning.
`vp run docgen` doesn't just type-check JSDoc `@example` blocks — it **compiles them as ESM and runs them**. `@effect/docgen` covers the examples on modules, functions, constants, types, namespaces and class methods. The task's second sub-task, `scripts/docgen-class-examples.ts`, covers the `@example` in a class's own doc comment, which docgen skips (#276). Neither covers an `@example` on a class property or constructor yet (#288). Note this is a separate command/CI step from `vp check` + `vp run check` + `vp run -r test:unit` — those passing does not mean your examples run; run `docgen` too before you're done. A broken example fails the build, not a lint warning.

Consequences for any `@example` in `src/*.ts`:

Expand All @@ -31,7 +31,7 @@ Consequences for any `@example` in `src/*.ts`:

This restriction is **specific to `src/*.ts` JSDoc examples**. `declare const` is fine in `test/*.types.ts` (see below) — those files are asserted by `tsc`, never executed by docgen or vitest. `src/index.ts` is excluded from docgen (`docgen.json`), so nothing executes its module doc; keep it free of code samples.

Docgen drives TypeScript through the JS API, so it sees the TS6 side of the split with its own compiler options (`docgen.json`; `types: ["node"]` is explicit because TypeScript 6 no longer auto-includes `@types`).
Docgen parses `src/` through the TypeScript JS API, so its parse sees the TS6 side of the split, under `parseCompilerOptions` in `docgen.json`. It compiles the examples by spawning the `tsc` on `PATH`, which under `vp run` is the native TS7 `tsc`, under `examplesCompilerOptions`. The class-example runner spawns the same `tsc`. `types: ["node"]` is explicit in both option sets because TypeScript 6 no longer auto-includes `@types`.

## Architecture

Expand Down Expand Up @@ -82,7 +82,7 @@ The same split explains why filtering has two forms with different flat encoding
- `vp check` — format + lint (Oxfmt + Oxlint). `vp run check` — the type gate: sources + colocated tests + type-level tests (`typecheck`), the emitted declarations (`typecheck:dist`, which builds `dist/` first) and every example. They are different commands.
- `vp run -r test:unit` — the root suite and each example's, under `vite-plus/test`.
- `vp run build` — `vp pack` → `dist/`.
- `vp run docgen` — type-check and execute every JSDoc `@example`; generate the API docs under `docs/`.
- `vp run docgen` — type-check and execute every JSDoc `@example` (class-property examples excepted, #288); generate the API docs under `docs/`.
- `fallow audit --base origin/trunk` — change-set review (dead code, complexity, duplication); not a CI gate.
- `pnpm changeset` — add a changeset.

Expand Down
Loading