Repository navigation
Require explicit @stability on every module and importable export - #8770
Conversation
🦋 Changeset detectedLatest commit: 1e14d65 The changes in this PR will be included in the next version bump. This PR includes changesets to release 32 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Bundle Size AnalysisGenerated from PR build output; treat the content below as untrusted.
|
|
@tim-smart @gcanti please review your respective modules (and also broadly) and decide on a case by case basis. We've missed quite a few (lacking explicit markers). |
|
/effect-bot do you think there is anything we might have missed here? |
effect-bot
left a comment
There was a problem hiding this comment.
Reviewed the current head, including stability classifications, directly importable exports, JSDoc enforcement, and barrel generation. The seven requested modules and their barrel exports are stable. I found two gaps in the new enforcement contract (inline comments).
Validation: the 27 existing JSDoc/codegen tests pass; pnpm jsdocs --check and pnpm lint pass; rerunning pnpm codegen leaves no diff. Temporary negative probes reproduced both enforcement gaps and were removed; no source changes or commits were made.
Non-blocking: the PR description still lists Filter, Latch, Pull, Semaphore and UndefinedOr as newly unstable, although they are now stable; the classification counts should be refreshed too.
| - name: Lint | ||
| run: pnpm lint | ||
| - name: Check JSDoc | ||
| run: pnpm jsdocs --check |
There was a problem hiding this comment.
[P2] Include public index exports in the stability check
The new CI command uses jsdocs.config.json, which excludes packages/**/src/index.ts altogether. This is not limited to generated barrels: the complete hand-maintained API of @effect/atom-vue and the entry-point exports of @effect/vitest are skipped as well. I removed every @stability tag from packages/atom/vue/src/index.ts locally and pnpm jsdocs --check still exited successfully. Consequently these directly importable exports have no enforcement despite the new all-exports requirement. Please add stability validation for public index files (a dedicated check is fine if the full JSDoc rules cannot apply), with a negative test for a hand-maintained index export.
| @@ -2759,7 +2770,9 @@ function parseDocumentedTs( | |||
| } | |||
| addModelDiagnostics(diagnostics, block.range, block.diagnostics) | |||
| if (block.parsed === undefined) return undefined | |||
| const tags = buildTags(scope, block.parsed.tags) | |||
| // Only names that can be imported directly require @stability. | |||
| const requireStability = scope === "declaration" || (scope === "namespace" && ts.isSourceFile(node.parent)) | |||
There was a problem hiding this comment.
[P2] Validate namespace re-exports as directly importable names
The new requirement only runs for nodes passed to parseDocumentedTs, but parseSourceFileDocs handles only ts.isNamedExports in its export-declaration branch and silently skips ts.NamespaceExport. Thus export * as Target from "./Target.ts" never reaches this check, even in an included non-index file. A negative extraction test using the new missingStabilityDiagnostics helper returned zero diagnostics for this export with its stability tag omitted. This export syntax is used throughout the public barrels, so including those files alone will not close the gap. Please validate the namespace-export JSDoc and require its stability tag, with a regression test for this syntax.
|
/effect-bot do you think anything is mis-categorized? We also need to make sure individual exports that use other unstable modules or apis are flagged as unstable, even if they are in a stable module. |
effect-bot
left a comment
There was a problem hiding this comment.
Dependency-sensitive classification audit of the latest head (01c4ebf4211af4594cd86b6c406a50a256b55c35): request changes. The inline findings are new classification issues, separate from the two enforcement gaps in my earlier review. Stable containing modules currently give stable tags to exports that expose or integrate explicitly unstable APIs: ExecutionPlan, ErrorReporter, ByteSize, filesystem/path/platform errors, and TxChunk. Please propagate instability at the individual-export level, including dependent public types.
The seven requested modules (Filter, Latch, Pull, Redactable, References, Semaphore, UndefinedOr) remain stable; I am not proposing to reverse those decisions. Existing unstable Graph, HTTP, and network schema wrappers are appropriate examples of the dependency-sensitive treatment. I found no additional module-level reclassification that I can justify from the current policy.
The earlier index-file exclusion and namespace re-export enforcement findings remain unchanged in the latest head; I have not duplicated their inline comments. The description still lists five of the requested stable modules as unstable and should be refreshed.
Validation for this pass was read-only source/signature and diff inspection, including the reporting implementation and prior review. No code or tests changed, no push, and no tests rerun.
|
/effect-bot can you fix those findings |
Modules that were not stable in effect 3.x are now tagged @stability unstable. All other modules are tagged @stability stable. The jsdocs linter and barrel codegen now accept @stability stable.
Tag every public declaration, export specifier, namespace, and namespace declaration in packages/effect with @stability, inheriting the module or namespace stability unless already tagged. The jsdocs linter enforces the tag for files matched by requireStability, and CI now runs pnpm jsdocs --check.
Declarations inside namespaces are reached through an import, so they no longer require their own @stability tag. Root declarations, export specifiers, and namespaces still do.
These packages were 0.x in effect 3.x. Tag every module and directly importable export @stability unstable so individual modules can be marked stable selectively, and extend requireStability to all packages.
Every package is now tagged, so the jsdocs linter requires @stability on module JSDoc, root declarations, export specifiers, and root namespaces without a config option.
96ed7e1 to
4a9f884
Compare
|
/effect-bot can you fix CI |
## pnpm-workspace.yaml (default) ## Dependency Updates | Package | From | To | Type | | --- | --- | --- | --- | | `@effect/platform-node` | 4.0.1 | 4.0.2 | patch | | `@effect/sql-d1` | 4.0.1 | 4.0.2 | patch | | `@effect/vitest` | 4.0.1 | 4.0.2 | patch | ## Release Notes <details> <summary><b>@<!---->effect/platform-node</b> (4.0.1 → 4.0.2)</summary> ### Patch Changes - [#8770](Effect-TS/effect#8770) [`540ecd1`](Effect-TS/effect@540ecd1) Thanks @<!---->fubhy! - Tag every module and directly importable export with an explicit `@stability`. `@stability stable` follows strict semver, and `@stability unstable` may receive breaking changes in minor releases. - [#8852](Effect-TS/effect#8852) [`7d8d497`](Effect-TS/effect@7d8d497) Thanks @<!---->effect-bot! - Report the `101` status of a successful WebSocket upgrade to server middleware such as `HttpMiddleware.logger` and `HttpMiddleware.tracer`, instead of the handler's discarded response status. - [#8846](Effect-TS/effect#8846) [`48a373b`](Effect-TS/effect@48a373b) Thanks @<!---->tim-smart! - Fix keep-alive requests hanging during graceful HTTP server shutdown. - Updated dependencies [[`26c1089`](Effect-TS/effect@26c1089), [`6c59de7`](Effect-TS/effect@6c59de7), [`467d3ac`](Effect-TS/effect@467d3ac), [`375c1b0`](Effect-TS/effect@375c1b0), [`45a70ce`](Effect-TS/effect@45a70ce), [`fb757e3`](Effect-TS/effect@fb757e3), [`716e358`](Effect-TS/effect@716e358), [`af114e6`](Effect-TS/effect@af114e6), [`d0b3862`](Effect-TS/effect@d0b3862), [`7064da9`](Effect-TS/effect@7064da9 …[full notes](https://github.com/Effect-TS/effect/releases/tag/%40effect/platform-node%404.0.2) </details> <details> <summary><b>@<!---->effect/sql-d1</b> (4.0.1 → 4.0.2)</summary> ### Patch Changes - [#8770](Effect-TS/effect#8770) [`540ecd1`](Effect-TS/effect@540ecd1) Thanks @<!---->fubhy! - Tag every module and directly importable export with an explicit `@stability`. `@stability stable` follows strict semver, and `@stability unstable` may receive breaking changes in minor releases. - [#8866](Effect-TS/effect#8866) [`00f1cc7`](Effect-TS/effect@00f1cc7) Thanks @<!---->Makisuo! - Align SQL tracing with OpenTelemetry database conventions: - Name statement spans by `db.namespace`, `server.address[:server.port]` or `db.system.name`, falling back to `sql.execute`. The rules are exported as `Statement.spanName` and `Statement.spanTarget`. - Record Effect execution methods in `effect.sql.method` instead of `db.operation.name`. - Use internal transaction spans with `effect.sql.transaction.commit|savepoint|rollback` events. - Name D1 batches of two or more statements `BATCH`, or `BATCH {target}` when a target is set, with `db.operation.name` set to `BATCH` and `db.operation.batch.size`. - [#8740](Effect-TS/effect#8740) [`ec54070`](Effect-TS/effect@ec54070) Thanks @<!---->tim-smart! - Update repository dependencies to their latest compatible releases. - Updated dependencies [[`26c1089`](Effect-TS/effect@26c1089), [`6c59de7`](Effect-TS/effect@6c59de7), [`467d3ac`](Effect-TS/effect@467d3ac), [`375c1b0`](Effect-TS/effect@375c1b0), [`45a70ce`](Effect-TS/effect@45a70ce), [`fb757e3`](Effect-TS/effect@fb757 …[full notes](https://github.com/Effect-TS/effect/releases/tag/%40effect/sql-d1%404.0.2) </details> <details> <summary><b>@<!---->effect/vitest</b> (4.0.1 → 4.0.2)</summary> ### Patch Changes - [#8770](Effect-TS/effect#8770) [`540ecd1`](Effect-TS/effect@540ecd1) Thanks @<!---->fubhy! - Tag every module and directly importable export with an explicit `@stability`. `@stability stable` follows strict semver, and `@stability unstable` may receive breaking changes in minor releases. - Updated dependencies [[`26c1089`](Effect-TS/effect@26c1089), [`6c59de7`](Effect-TS/effect@6c59de7), [`467d3ac`](Effect-TS/effect@467d3ac), [`375c1b0`](Effect-TS/effect@375c1b0), [`45a70ce`](Effect-TS/effect@45a70ce), [`fb757e3`](Effect-TS/effect@fb757e3), [`716e358`](Effect-TS/effect@716e358), [`af114e6`](Effect-TS/effect@af114e6), [`d0b3862`](Effect-TS/effect@d0b3862), [`7064da9`](Effect-TS/effect@7064da9), [`eee0eeb`](Effect-TS/effect@eee0eeb), [`b9d6581`](Effect-TS/effect@b9d6581), [`7a721ce`](Effect-TS/effect@7a721ce), [`a0cb4c2`](Effect-TS/effect@a0cb4c2), [`3cb395e`](Effect-TS/effect@3cb395e), [`540ecd1`](Effect-TS/effect@540ecd1), [`aefe05a`](https://gi …[full notes](https://github.com/Effect-TS/effect/releases/tag/%40effect/vitest%404.0.2) </details> --- *This PR was auto-generated by [catalog-update-action](https://github.com/brandhaug/catalog-update-action).* Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
- Add `@stability unstable` to each module JSDoc, each top-level export, and each interface the package adds to `effect/ai/Prompt` and `effect/ai/Response`, as Effect-TS#8770 requires and as the other AI providers do; the barrel's export blocks come from `effect-utils codegen`. The package's `tsc` now reports no `effect(apiStabilityLeak)` errors - Fix the JSDoc that `pnpm jsdocs --check` rejected in the package: titles for the two `**Example**` sections, a `**Details**` heading on the multi-paragraph `JsonSchemaDefinition` and `ConverseRequest` descriptions, and a code span for the `ConverseRequest` link to `AmazonBedrockLanguageModel.Config`, which does not resolve from the schema module - Regenerate `docs/modules`, which also picks up the schema and config changes from the Opus 5.5 structured-output fix - Add a minor changeset for the structured-output fix, and correct the tool-calling changeset, which said Converse has no native json_schema mode and that streaming tool calls are unsupported - Name the generateObject live test for both of its models, one of which takes the tool path, and say in TODO.md which models get the forced object tool Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every public module and directly importable declaration now has an explicit
@stabilitytag, with mandatory JSDoc enforcement and CI coverage.Closes EFF-1792
Module classification
Stable Effect 3.x modules retain stable status, including renamed successors identified by
migration/v3-to-v4.md: Result, JsonSchema, Formatter, Redactable, References, SchemaIssue, SchemaParser, SchemaTransformation, mapped Tx modules, testing/TestClock, and the encoding modules.Filter, Latch, Pull, Redactable, References, Semaphore, and UndefinedOr are explicitly stable, as requested. Combiner, JsonPatch, JsonPointer, Optic, Reducer, SchemaGetter, SchemaRepresentation, and StandardSchema also remain stable.
Unstable groups include:
Current source-header classification counts (non-internal source files, including entry points/barrels and generated/vendor module headers):
Dependency-sensitive export tags
Module stability is the default classification, not a guarantee about every export. This follow-up changes 56 individual declaration tags in stable Effect modules to unstable:
Containing module headers stay stable. Unrelated exports and APIs that use unstable implementations only internally are not blanket-reclassified.
Enforcement and generation
Verification
All commands run through
nix develop -c:pnpm jsdocs --check,pnpm lint,pnpm check, andgit diff --checkpass.pnpm codegenpasses and produces no additional diff.pnpm jsdocs --check,pnpm lint,pnpm check, andgit diff --checkpass. Combined JSDoc, codegen, and API-diff suites: 72 passed across 11 files.pnpm doctest --run packages/vitest/src/index.tsfound no test files (no doctest coverage claimed).A patch changeset covers effect and the other affected packages.