@sayoriqwq/effect-harness 0.0.1 → 0.0.2

package/repos/tsgo/.specs/perf-replace-iterchildren-with-foreachchild.md

@@ -0,0 +1,124 @@
+# Performance: Replace IterChildren with ForEachChild
+
+## Goal
+
+Eliminate the largest source of heap allocations in the Effect diagnostic pipeline by migrating all AST traversals from `IterChildren` to `ForEachChild`.
+
+## Problem
+
+Profiling shows `IterChildren` + `invert` account for **178 million allocations (39% of total)** in a full project check. Every `IterChildren()` call allocates 2 closures:
+
+1. The Go `iter.Seq[*Node]` iterator function (captures the node receiver).
+2. The `invert(yield)` wrapper that flips boolean semantics (`Visitor` returns `true` to stop vs Go iterators return `false` to stop).
+
+With 40 rules and 3 type parsers all walking the AST via `IterChildren`, this multiplies to billions of allocations across a full project build, creating massive GC pressure. The aggregate allocation count (12B vs 966M for standard tsgo) is the primary cause of the ~4x check time regression.
+
+## Solution
+
+Replace all `IterChildren` usage with `ForEachChild`, the zero-allocation callback pattern that TypeScript-Go's own checker uses internally.
+
+### Before (allocating)
+
+```go
+var walk func(n *ast.Node)
+walk = func(n *ast.Node) {
+    if n == nil { return }
+    // ... node processing ...
+    for child := range n.IterChildren() {  // 2 closures per node
+        walk(child)
+    }
+}
+walk(sf.AsNode())
+```
+
+### After (zero allocation)
+
+```go
+var walk ast.Visitor
+walk = func(n *ast.Node) bool {
+    if n == nil { return false }
+    // ... node processing ...
+    n.ForEachChild(walk)
+    return false  // false = continue visiting siblings
+}
+walk(sf.AsNode())
+```
+
+### Boolean semantics
+
+- `ForEachChild`'s `Visitor` returns `true` to **stop early** (break), `false` to **continue**.
+- This is the inverse of Go's `yield` convention. The `invert` wrapper exists solely to bridge this gap — by calling `ForEachChild` directly, the wrapper is eliminated.
+
+### Stack-based traversal adaptation
+
+```go
+stack := []*ast.Node{sf.AsNode()}
+for len(stack) > 0 {
+    node := stack[len(stack)-1]
+    stack = stack[:len(stack)-1]
+    // ... node processing ...
+    node.ForEachChild(func(child *ast.Node) bool {
+        stack = append(stack, child)
+        return false
+    })
+}
+```
+
+## Files to migrate
+
+### Rules (40 files in `internal/rules/`)
+
+All rule files currently using `IterChildren`:
+
+- `any_unknown_in_error_context.go`
+- `class_self_mismatch.go`
+- `deterministic_keys.go`
+- `effect_fn_iife.go`
+- `effect_fn_opportunity.go`
+- `effect_gen_uses_adapter.go`
+- `effect_in_failure.go`
+- `effect_map_void.go`
+- `effect_succeed_with_void.go`
+- `extends_native_error.go`
+- `floating_effect.go`
+- `generic_effect_services.go`
+- `global_error_in_effect_catch.go`
+- `global_error_in_effect_failure.go`
+- `instance_of_schema.go`
+- `layer_merge_all_with_dependencies.go`
+- `leaking_requirements.go`
+- `missing_effect_service_dependency.go`
+- `missing_return_yield_star.go`
+- `missing_star_in_yield_effect_gen.go`
+- `non_object_effect_service_type.go`
+- `outdated_api.go`
+- `overridden_schema_constructor.go`
+- `prefer_schema_over_json.go`
+- `redundant_schema_tag_identifier.go`
+- `return_effect_in_gen.go`
+- `run_effect_inside_effect.go`
+- `schema_struct_with_tag.go`
+- `schema_sync_in_effect.go`
+- `schema_union_of_literals.go`
+- `scope_in_layer_effect.go`
+- `service_not_as_class.go`
+- `strict_boolean_expressions.go`
+- `strict_effect_provide.go`
+- `try_catch_in_effect_gen.go`
+- `unknown_in_effect_catch.go`
+- `unnecessary_effect_gen.go`
+- `unnecessary_fail_yieldable_error.go`
+- `unnecessary_pipe.go`
+- `unnecessary_pipe_chain.go`
+
+### Type parsers (3 files in `internal/typeparser/`)
+
+- `piping_flow.go`
+- `expected_and_real_type.go`
+- `effect_fn_opportunity.go`
+
+## Acceptance Criteria
+
+1. Zero remaining uses of `IterChildren` in `internal/rules/` and `internal/typeparser/`.
+2. All existing tests pass with no behavioral changes.
+3. Measurable reduction in aggregate allocation count (target: eliminate ~178M allocations from IterChildren + invert).

package/repos/tsgo/.specs/quick-fix-baselines.md

@@ -0,0 +1,59 @@
+# Quick Fix Baselines
+
+## Goal
+Provide deterministic, human-readable baseline outputs that show (1) which quick fixes are available for each reported diagnostic and (2) what each quick fix changes when applied.
+
+## Scope
+- Applies to the Effect diagnostic baseline workflow under `testdata/baselines`.
+- Covers baseline output contract for a new `*.quickfixes.txt` artifact.
+- Covers multi-file test cases and diagnostics with multiple quick fixes.
+- Covers quick-fix outputs for Effect V4 test baselines.
+- Covers a minimal `fourslash` patch surface needed to list and apply quick fixes from tests.
+- Covers a generic quick-fix baseline runner for both Effect V3 and Effect V4 test directories.
+
+## Requirements
+1. `*.errors.txt` formatting and content contract must remain unchanged.
+2. A new `*.quickfixes.txt` baseline artifact must be generated for each test case alongside existing baseline artifacts.
+3. The top section of `*.quickfixes.txt` must include, for each diagnostic occurrence:
+- the stable diagnostic identifier,
+- the diagnostic code and message,
+- the list of available quick-fix titles in deterministic order.
+4. The stable diagnostic identifier must be deterministic for a given test input and must distinguish repeated occurrences of the same diagnostic code in the same file.
+5. `*.quickfixes.txt` must include an application-result entry for each available quick fix for each diagnostic occurrence.
+6. Quick-fix application results in `*.quickfixes.txt` must be grouped by diagnostic occurrence and quick-fix index so every applied result is uniquely addressable.
+7. For multi-file tests, quick-fix application output must clearly show which files changed for each applied quick fix.
+8. For multi-file quick-fix results, changed files must be emitted in deterministic path order.
+9. For each changed file, `*.quickfixes.txt` must include readable post-apply (`after`) output suitable for snapshot review.
+10. If applying a quick fix creates or deletes files, `*.quickfixes.txt` must explicitly label file lifecycle events (created or deleted).
+11. If a quick fix is available but produces no text edits for a diagnostic occurrence, `*.quickfixes.txt` must record it as a no-op result.
+12. Baseline generation must preserve existing deterministic ordering guarantees by sorting diagnostics and quick-fix entries consistently.
+13. The baseline contract must avoid coupling to implementation-specific internals; it must validate user-visible quick-fix titles and text-edit outcomes.
+14. The baseline workflow must continue to pass the repository validation workflow without regressions to existing baseline artifacts.
+15. Preferred delivery approach: add only the minimal methods needed in patched `fourslash` test APIs to (a) list quick fixes for a diagnostic context and (b) apply a selected quick fix.
+16. Effect quick-fix baseline generation must use those `fourslash` methods in its runner flow rather than relying on the existing non-fourslash diagnostics runner implementation.
+17. The quick-fix baseline generation must run through a generic fourslash-based runner that discovers all TypeScript test files in `testdata/tests/effect-v3` and `testdata/tests/effect-v4`, following the same per-version test-file discovery behavior used by the existing `*.errors.txt` baseline runner.
+18. The generic runner must generate one `*.quickfixes.txt` baseline per discovered TypeScript test file in the corresponding versioned baseline output folder.
+19. In the fourslash-based baseline flow, Effect-version-specific test library injection must be selected per test file, not through shared global process state.
+20. In the fourslash-based baseline flow, a test file that starts with the marker comment `// @effect-v3` must be treated as an Effect v3 test for library injection.
+21. In the fourslash-based baseline flow, if the v3 marker is not present, the runner must default that test file to Effect v4 library injection.
+22. All fourslash test files under `testdata/tests/effect-v3` must include the `// @effect-v3` marker at the beginning of the file.
+23. Disable-style quick fixes with titles matching `Disable ... for this line` or `Disable ... for entire file` must remain listed in the quick-fix inventory but must not emit file-change output in application results.
+24. For those disable-style quick fixes, the application-result entry must be recorded as `skipped by default`.
+
+## Non-Goals
+- Defining a new language-service protocol.
+- Changing quick-fix semantics or quick-fix title wording.
+- Introducing requirements for non-Effect test suites.
+- Large or unrelated patch expansion in `typescript-go`.
+
+## Acceptance Criteria
+1. `*.errors.txt` remains unchanged.
+2. `*.quickfixes.txt` exists for baseline test cases and is deterministic across repeated runs.
+3. The top section of `*.quickfixes.txt` contains diagnostic-indexed quick-fix inventory for all diagnostic occurrences in the test.
+4. For diagnostics with multiple quick fixes, each fix has a distinct application-result entry (either applied output, no-op/create/delete result, or `skipped by default`).
+5. Multi-file quick-fix application results clearly identify changed files and their post-apply (`after`) outputs.
+6. No-op, create-file, delete-file, and `skipped by default` quick-fix outcomes are explicitly represented.
+7. Existing and new baseline outputs are reviewable and sufficient to verify that current quick fixes match expected behavior.
+8. The solution is delivered via minimal `fourslash` patch additions plus Effect test-suite output updates, without broader harness redesign.
+9. A generic fourslash-based runner processes both Effect V3 and Effect V4 test folders and emits per-test `*.quickfixes.txt` outputs.
+10. The fourslash-based baseline runs correctly inject Effect v3 libraries for marker-tagged tests and Effect v4 libraries for untagged tests.

package/repos/tsgo/.specs/refactor-infrastructure.md

@@ -0,0 +1,93 @@
+# Refactor Infrastructure
+
+## Goal
+
+Provide a refactor framework mirroring the existing fixable infrastructure (`internal/fixable/` and `internal/fixables/`), but for selection-based refactoring actions that are not tied to a specific diagnostic.
+
+## Background
+
+The fixable infrastructure handles code fixes triggered by diagnostics: a fixable declares the error codes it handles, and the LS dispatches to it when a code action is requested for a matching diagnostic. Refactors are different — they are triggered by any text selection, regardless of whether a diagnostic is present. In the LSP protocol, both flow through `textDocument/codeAction` but differ in their `CodeActionKind` (`quickfix` vs `refactor.rewrite.*`).
+
+## Scope
+
+- A new `internal/refactor/` package providing the refactor context and types.
+- A new `internal/refactors/` package providing the registry of all refactors.
+- A new `RegisterRefactorProvider` hook in typescript-go (patch + shim).
+- Wiring in `etslshooks`.
+
+## Requirements
+
+### Registration Hook (typescript-go patch)
+
+1. A `RefactorProvider` type must be added to the language service, analogous to `CodeFixProvider`:
+   - It must expose a `GetRefactorActions` function that receives a context, source file, and text span, and returns refactor code actions.
+   - It must not require an error code or diagnostic — refactors apply to any selection.
+2. A `RegisterRefactorProvider` function must be added, appending to an `externalRefactorProviders` slice (analogous to `externalCodeFixProviders`).
+3. The `ProvideCodeActions` function must be extended with a code path that invokes refactor providers when the request's `CodeActionKind` filter includes `refactor.*` kinds, or when no filter is specified.
+4. The server capability advertisement must include `refactor.rewrite` as a supported code action kind.
+5. The shim must be regenerated to expose the new hook.
+
+### Refactor Context (`internal/refactor/`)
+
+6. A `Refactor` struct must be introduced (analogous to `fixable.Fixable`):
+   - `Name string` — unique identifier for the refactor
+   - `Description string` — user-visible label in the refactor menu
+   - `Kind string` — the `CodeActionKind` suffix (e.g., `"rewrite.effect.wrapWithPipe"`)
+   - `Run func(ctx *Context) []ls.CodeAction` — the refactor implementation
+
+7. A `Context` struct must be introduced (analogous to `fixable.Context`), wrapping the refactor request data:
+   - `SourceFile *ast.SourceFile` — the file being refactored
+   - `Span core.TextRange` — the selected text range
+
+8. The context must expose the same helper methods as the fixable context:
+   - `GetTypeCheckerForFile(sf *ast.SourceFile) (*checker.Checker, func())` — returns a checker and cleanup handle
+   - `NodeFactory` — for AST node construction
+   - `NewRefactorAction(action RefactorAction) *ls.CodeAction` — analogous to `NewFixAction`
+   - `FormatOptions() *lsutil.FormatCodeSettings`
+
+9. `RefactorAction` must mirror `FixAction`:
+   - `Description string` — user-visible code action name
+   - `Run func(tracker *change.Tracker)` — closure that performs edits on a fresh tracker
+
+10. `NewRefactorAction` must follow the same lifecycle as `NewFixAction`: create tracker, call `Run`, finalize, return `*ls.CodeAction` (or `nil` if no edits).
+
+### Refactors Registry (`internal/refactors/`)
+
+11. A `var All []refactor.Refactor` registry must be maintained, listing all registered refactors (analogous to `fixables.All`).
+12. Each refactor must be declared in its own file within `internal/refactors/`.
+13. Adding a new refactor requires: creating the file, declaring the `refactor.Refactor` var, and appending it to `All`.
+
+### Wiring (`etslshooks`)
+
+14. `etslshooks/init.go` must register a single `RefactorProvider` that dispatches to all refactors in the registry.
+15. The dispatch logic iterates all refactors in `All`, calls each `Run(ctx)`, and concatenates the resulting code actions.
+16. Unlike fixables (which dispatch by error code), refactors all run on every request — each refactor's `Run` function is responsible for checking applicability and returning an empty slice when not applicable.
+
+### Applicability Pattern
+
+17. Each refactor's `Run` function must check whether the refactor is applicable to the current selection. If not applicable, it returns `nil` (no actions). If applicable, it returns one or more code actions via `ctx.NewRefactorAction`.
+18. Applicability checks are the responsibility of individual refactors — the framework does not pre-filter.
+
+### Testing
+
+19. Refactor tests live in `testdata/tests/effect-v4-refactors/`. Each `.ts` test file generates a `*.refactors.txt` baseline.
+20. Selection ranges for refactor tests must be specified using a comment on the first line of the file. The comment is NOT stripped from the source — it remains part of the file so that line numbers in the range specifications stay correct.
+21. The format follows the convention from the original language service: `// refactor: L:C-L:C,L:C-L:C` where each `L:C-L:C` is a range (startLine:startCol-endLine:endCol, 1-based lines and columns), and multiple ranges are separated by commas. A single `L:C` (without dash) denotes a point selection.
+22. The test runner must parse the `// refactor:` comment to extract selection ranges but must NOT remove it from the source before processing.
+23. A test file without a `// refactor:` comment must be tested with an empty selection (0:0–0:0), verifying that no refactors are offered.
+24. The refactor baseline runner must also test with an empty selection (0:0–0:0) in addition to the marked selections, to verify that refactors are not offered when nothing is selected.
+25. The baseline output format must match the established quick-fix baseline style: an inventory section listing available refactors per selection, followed by application-result sections showing the post-apply source.
+
+## Non-Goals
+
+- Multi-file workspace edits (refactors are scoped to a single source file, same as fixables).
+- "Fix all" / "Refactor all" support (no equivalent of `FixIds` or `GetAllCodeActions` for refactors).
+- Changing existing fixable infrastructure or diagnostic detection.
+
+## Acceptance Criteria
+
+1. A `RegisterRefactorProvider` hook exists in the shim and is callable from Effect code.
+2. The `refactor.Context` provides the same capabilities as `fixable.Context` (checker access, node factory, tracker-based edit generation via `NewRefactorAction`).
+3. Refactors registered in `internal/refactors/All` are invoked for `textDocument/codeAction` requests that include `refactor.*` kinds.
+4. Refactor actions appear in the editor's refactor menu (not the quick-fix menu).
+5. The framework supports adding new refactors by creating a file + appending to the registry, with no other wiring needed.

package/repos/tsgo/.specs/release-prepare.md

@@ -0,0 +1,39 @@
+# Release Prepare Command
+
+## Goal
+Define a single command that prepares release-ready workspace packages for preview or snapshot publishing from CI.
+
+## Scope
+- Applies to the repository-level release preparation workflow.
+- Covers publishable npm packages defined under `_packages`.
+- Covers preparation of platform-specific `tsgo` binary artifacts into the publishable package locations under `_packages`.
+- Covers behavior of the single command contract exposed to CI.
+- Covers the GitHub Actions release workflow's integration with target selection.
+
+## Requirements
+1. The project must expose a single `release:prepare` command that CI can call as the canonical release-preparation entrypoint.
+2. Publishable package manifests must be maintained as real workspace packages under `_packages` rather than synthesized into a detached output tree.
+3. Running `release:prepare` must prepare publish-ready workspace packages in `_packages`, including all required package metadata for packaging/publishing workflows.
+4. `release:prepare` must cross-compile platform-specific `tsgo` binaries directly into the corresponding publishable package locations under `_packages`. No intermediate build directory should be used.
+5. `release:prepare` must perform its steps in this order: first cross-compile all platform binaries sequentially, then build the CLI bundle.
+6. The script must accept a repeatable `--target <platform-arch>` flag to select which platform targets to build (e.g., `--target linux-x64 --target darwin-arm64`). When no `--target` flags are provided, all targets are built. Target identifiers use the `<npm_platform>-<npm_arch>` format matching the package naming convention (e.g., `linux-x64`, `darwin-arm64`, `win32-x64`).
+7. Artifact validation must only check the targets that were actually selected for the current run.
+8. The GitHub Actions release workflow must use a static matrix strategy to build platform binaries in parallel. Platform selection must be controlled by `workflow_dispatch` boolean inputs (checkboxes in the manual trigger UI), not by hardcoded matrix `enabled` values in the workflow file. Each matrix job evaluates whether its target is selected by those inputs; selected targets run `release-prepare --target <platform> --skip-cli` and upload artifacts, while unselected targets are skipped via step-level `if` conditions and remain visible in the job list. A final publish job (with `needs` on the matrix job) downloads only artifacts from selected targets into the correct `_packages` locations, builds the CLI bundle, and runs a single `pkg.pr.new publish` invocation with all selected packages.
+10. The script must accept a `--skip-cli` flag that skips the CLI bundle build step. When `--skip-cli` is set, only binary compilation and validation are performed. This is used by the matrix build jobs, which only need to produce the binary artifact.
+11. `release:prepare` must fail fast with actionable errors if required release inputs or artifacts are missing.
+12. `release:prepare` must be repeatable in CI: reruns should converge to a consistent publish-ready state without manual cleanup.
+13. The command must preserve existing architecture and setup constraints documented for this repository (including required generated artifacts and patch setup prerequisites).
+14. Release workflow dependency installation must run with lockfile immutability enabled, and the repository must include the root `pnpm-lock.yaml` required for frozen installs.
+
+## Non-Goals
+- Performing the publish step itself.
+- Defining external registry release policy.
+- Changing end-user CLI behavior.
+
+## Acceptance Criteria
+1. A CI job can call one command, `release:prepare`, to produce the full publish-ready workspace package set.
+2. After `release:prepare`, the main CLI package and platform-specific binary packages in `_packages` are ready to be published.
+3. The prepared workspace package paths can be consumed directly by `pkg.pr.new publish` invocations (one per platform binary in the matrix, one for the CLI package in the publish job).
+4. Missing inputs or incomplete artifacts are surfaced as clear command failures before publish.
+5. In a manual workflow dispatch, users can choose target platforms through checkbox inputs, and only selected platform jobs are built/published.
+6. A clean checkout can execute release workflow dependency installation with `pnpm install --frozen-lockfile` without lockfile-related failures.

package/repos/tsgo/.specs/rule-context.md

@@ -0,0 +1,82 @@
+# Rule Context
+
+## Goal
+
+Reduce boilerplate in diagnostic rule implementations by introducing a `rule.Context` type that replaces the current `(c *checker.Checker, sf *ast.SourceFile)` signature with a single context parameter, and provides a `NewDiagnostic` helper that hides the verbose `ast.NewDiagnosticFromSerialized` call.
+
+## Scope
+
+- The `rule.Context` type in the `rule` package.
+- The `Run` function signature on `rule.Rule`.
+- All rule implementations in `internal/rules/`.
+- The `Analyze*` functions and their match structs in `internal/rules/`.
+- The fixables in `internal/fixables/` that consume `Analyze*` results.
+- The call site in `etscheckerhooks/init.go` that invokes `rule.Run`.
+
+## Requirements
+
+### rule.Context type
+
+1. `rule.Context` must contain:
+   - `SourceFile` — the source file being checked.
+   - `Checker` — the type checker instance.
+   - A `NewDiagnostic` method for creating diagnostics.
+
+2. `NewDiagnostic` must accept:
+   - A location as `core.TextRange` (the pre-computed error range).
+   - A diagnostic message (the `*diagnostics.Message` struct, e.g. `tsdiag.Effect_must_be_...`). This replaces the separate code, category, and key parameters.
+   - Related diagnostics as `[]*ast.Diagnostic` (pass `nil` when none).
+   - Message args as variadic `...string` (for `{0}`, `{1}` placeholders).
+
+   The `rule.Context` must also provide a `GetErrorRange(node *ast.Node) core.TextRange` helper that wraps `scanner.GetErrorRangeForNode(ctx.SourceFile, node)`. Rules that don't use `Analyze*` functions can use this to compute a location from a node before passing it to `NewDiagnostic`.
+
+3. `NewDiagnostic` must NOT accept a severity parameter. The severity used in the created diagnostic must come from the rule's `DefaultSeverity` field. This is the initial category embedded in the diagnostic; the existing `transformDiagnostics` pipeline continues to override it based on user config and directives.
+
+4. `NewDiagnostic` must return an `*ast.Diagnostic` with the same structure as today's `ast.NewDiagnosticFromSerialized`, using `false` for `reportsUnnecessary`, `reportsDeprecated`, and `skippedOnNoEmit`.
+
+### Rule.DefaultSeverity
+
+5. The `DefaultSeverity` field on `rule.Rule` must change from `*etscore.Severity` (pointer, nil = error) to `etscore.Severity` (plain value). Every rule must explicitly set its default severity. The `EffectiveDefaultSeverity()` method and the `etscore.SeverityPtr` helper function must be removed since they are no longer needed.
+
+### Rule.Run signature
+
+6. The `Run` field on `rule.Rule` must change from `func(c *checker.Checker, sf *ast.SourceFile) []*ast.Diagnostic` to `func(ctx *rule.Context) []*ast.Diagnostic`.
+
+### Call site updates
+
+7. `etscheckerhooks/init.go` must construct a `rule.Context` for each rule invocation, passing the checker, source file, and the rule's default severity (so that `NewDiagnostic` can use it internally). References to `EffectiveDefaultSeverity()` must be replaced with direct access to `DefaultSeverity`.
+
+### Rule migration
+
+8. All existing rules in `internal/rules/` must be migrated to use `*rule.Context`:
+   - Replace `c` with `ctx.Checker` and `sf` with `ctx.SourceFile`.
+   - Replace `create*Diagnostic` helper functions with calls to `ctx.NewDiagnostic`.
+   - Remove the now-unnecessary `create*Diagnostic` helper functions.
+   - Remove imports that are no longer needed (`directives`, `etscore`, `scanner`) from rules that no longer reference them directly.
+
+### Analyze functions and match structs
+
+9. The `Analyze*` functions must NOT create diagnostics. They must return match structs that contain only the data needed for both diagnostic creation and code fixes — primarily AST nodes and parsed results.
+
+10. Every match struct must replace its `Diagnostic *ast.Diagnostic` field with a `Location core.TextRange` field containing the pre-computed error range. The `Analyze*` function computes this via `scanner.GetErrorRangeForNode(sf, node)` at detection time.
+
+11. The rule's `Run` function must create diagnostics from the match data using `ctx.NewDiagnostic(match.Location, ...)`.
+
+12. Fixables in `internal/fixables/` must use `match.Location` directly for range comparison instead of extracting it from `match.Diagnostic.Loc()`.
+
+## Non-Goals
+
+- Changing how directives or severity overrides work (the `transformDiagnostics` pipeline stays as-is).
+- Changing the diagnostic message definitions or the `diagnostics.Message` type.
+- Moving the rules to a different package.
+- Changing rule registration or the `rules.All` slice.
+
+## Acceptance Criteria
+
+1. All existing rules compile and pass tests after migration.
+2. No rule directly calls `ast.NewDiagnosticFromSerialized` for its primary diagnostics — they all use `ctx.NewDiagnostic` instead.
+3. No rule imports `directives` or `etscore` solely for diagnostic creation boilerplate.
+4. The `Run` signature on `rule.Rule` is `func(ctx *rule.Context) []*ast.Diagnostic`.
+5. No `Analyze*` function creates diagnostics or returns a `Diagnostic` field in its match struct.
+6. All fixables use `match.Location` directly, not a diagnostic object.
+7. The full validation workflow passes without errors.

package/repos/tsgo/.specs/scope-aware-global-diagnostics.md

@@ -0,0 +1,68 @@
+# Scope-Aware Global Diagnostics
+
+## Goal
+
+Port the reference implementation's scope-aware global API diagnostics into the Go language service so users receive different guidance for global API usage inside Effect-yielding scopes versus outside them.
+
+## Scope
+
+- Covers the global API diagnostics for `fetch`, `console`, `Date`, `Math.random`, `setTimeout`, and `setInterval`.
+- Covers both outside-Effect and inside-Effect rule variants where the reference implementation now splits behavior by scope.
+- Covers shared symbol normalization needed to reliably recognize global APIs through aliases and simple indirections.
+- Covers diagnostic message wiring, rule registration, metadata exposure, tests, and README updates for the new and renamed diagnostics.
+
+## Requirements
+
+1. The Go implementation must match the final reference behavior after `Effect-TS/language-service` commit `5814a58`, not the intermediate unsplit behavior from `78e78d5`.
+2. The rule set must expose separate diagnostics for global API usage outside Effect-yielding scopes and inside Effect-yielding scopes whenever the reference implementation does so.
+3. The following diagnostic names must be supported:
+   - `globalFetch`
+   - `globalFetchInEffect`
+   - `globalConsole`
+   - `globalConsoleInEffect`
+   - `globalDate`
+   - `globalDateInEffect`
+   - `globalRandom`
+   - `globalRandomInEffect`
+   - `globalTimers`
+   - `globalTimersInEffect`
+4. Scope classification must reuse the existing Go Effect context analysis rather than introducing a parallel scope-detection system.
+5. Outside-Effect diagnostics must report only matches that are not inside an Effect-yielding scope.
+6. In-Effect diagnostics must report only matches that are inside an Effect-yielding scope.
+7. `globalFetch` and `globalFetchInEffect` must preserve version-aware guidance:
+   - use `@effect/platform` messaging for Effect v3
+   - use `effect/unstable/http` messaging for Effect v4
+8. The implementation must add a shared symbol-normalization helper so diagnostics can recognize the underlying global symbol even when the code uses:
+   - direct global references
+   - aliased references
+   - simple variable indirections that still resolve to the same global value
+9. The symbol-normalization behavior should be shared across the global diagnostics rather than copied into each rule.
+10. `globalConsole` and `globalConsoleInEffect` must cover the console methods supported by the reference implementation: `log`, `warn`, `error`, `info`, `debug`, and `trace`.
+11. `globalDate` and `globalDateInEffect` must distinguish the reference implementation's supported forms:
+   - `Date.now()` guidance
+   - `new Date()` guidance
+12. `globalRandom` and `globalRandomInEffect` must cover `Math.random()`.
+13. `globalTimers` and `globalTimersInEffect` must cover `setTimeout` and `setInterval`, with diagnostic guidance matching the reference implementation's preferred Effect alternatives.
+14. The diagnostic metadata and generated diagnostic messages must include all newly introduced rule names and message texts needed by the split rules.
+15. The committed README diagnostics table must be updated to reflect the final scope-aware rule set and descriptions.
+16. Test coverage must verify, at minimum:
+   - outside-Effect matches
+   - inside-Effect matches
+   - no duplicate reporting between the split variants
+   - alias or simple-indirection recognition for global APIs
+   - v3/v4-specific `globalFetch` messaging
+
+## Non-Goals
+
+- Adding quick fixes for these diagnostics.
+- Changing the existing Effect context analysis model beyond what is needed to consume it.
+- Porting unrelated diagnostics that landed after these commits.
+
+## Acceptance Criteria
+
+1. A project using a supported global API outside an Effect-yielding scope receives only the outside-Effect diagnostic variant.
+2. A project using the same API inside an Effect-yielding scope receives only the corresponding `InEffect` diagnostic variant.
+3. `globalFetch` messaging changes based on detected supported Effect version exactly as in the reference implementation.
+4. The Go diagnostics can still recognize targeted global APIs when code introduces a simple alias or variable indirection.
+5. The diagnostics table in `README.md` lists the full final scope-aware rule set and descriptions.
+6. Repository validation and baseline coverage confirm the new rules are registered and emitted with the expected names and messages.

package/repos/tsgo/.specs/setup-diagnostic-prompt-parity.md

@@ -0,0 +1,47 @@
+# Setup Diagnostic Prompt Parity
+
+## Goal
+
+Adopt the upstream setup diagnostic prompt flow in the tsgo package once tsgo exposes the same generated diagnostic metadata structure expected by the reference implementation.
+
+## Scope
+
+- Covers the setup diagnostic prompt used when configuring diagnostic severities.
+- Covers parity with the upstream prompt behavior and metadata contract.
+- Assumes the grouped `metadata.json` structure and preview payloads already exist in tsgo.
+
+## Relationship To Other Specs
+
+This spec depends on:
+
+- [`.specs/diagnostic-metadata-generation.md`](../../.specs/diagnostic-metadata-generation.md)
+- [`.specs/diagnostic-metadata-previews.md`](../../.specs/diagnostic-metadata-previews.md)
+
+Those specs establish the generated metadata structure that this prompt consumes.
+
+## Reference Implementation
+
+The canonical prompt implementation lives in the upstream reference repository:
+
+- `.repos/effect-language-service/packages/language-service/src/cli/setup/diagnostic-prompt.ts`
+
+The expectation for this work is to reuse that prompt behavior as directly as practical in tsgo once the metadata contract matches.
+
+## Requirements
+
+1. The tsgo setup flow must read diagnostic metadata from the generated `metadata.json` structure established by the metadata specs.
+2. The setup diagnostic prompt should match the upstream prompt interaction model as closely as practical, including grouped browsing, search, preview rendering, and severity adjustment behavior.
+3. The prompt adoption work should minimize local divergence from the upstream prompt logic so future parity updates stay straightforward.
+4. The prompt must operate correctly against tsgo-generated metadata without introducing a separate tsgo-only metadata shape.
+
+## Non-Goals
+
+- Redefining the metadata format for setup.
+- Reworking setup beyond the diagnostic prompt experience.
+- Introducing a custom tsgo-only prompt design when upstream parity is sufficient.
+
+## Acceptance Criteria
+
+1. After metadata generation and preview generation are in place, tsgo can use the upstream-style diagnostic prompt against its own generated `metadata.json`.
+2. The prompt behavior remains aligned with the upstream reference implementation rather than becoming a separate local design.
+3. The prompt consumes the same metadata shape produced for README and metadata generation work.

package/repos/tsgo/.specs/setup-implicit-prepare-script.md

@@ -0,0 +1,27 @@
+# Setup Command: Implicit Prepare Script
+
+## Goal
+Remove the prepare script prompt from the setup command. The prepare script is now an implicit consequence of install/uninstall — not a user choice.
+
+## Background
+The Go-based language service (`@effect/tsgo`) uses a binary architecture. There is no "LSP-only" mode — the prepare script patches the TypeScript compiler to enable Effect diagnostics during compilation. Since the binary is all-or-nothing, asking whether to enable patching is unnecessary: if the user installs, they get the prepare script; if they uninstall, it's removed.
+
+## Requirements
+
+1. The setup command must not prompt the user about the prepare script.
+2. When the user chooses to install the language service (any dependency type), `prepareScript` in the target state must be `true` automatically.
+3. When the user chooses to uninstall the language service, `prepareScript` in the target state must be `false` automatically.
+4. The `Target.PackageJson` type may keep the `prepareScript` field (it's still needed by `computeChanges()`), but it must be derived from the install/uninstall choice, not from user input.
+5. After applying install changes, the setup command must display a message suggesting the user run `effect-tsgo patch` to complete the installation.
+6. After applying uninstall changes, the setup command must display a message suggesting the user run `effect-tsgo unpatch` to restore the original TypeScript-Go binary.
+
+## Non-Goals
+- Changing which dependency type options are available (devDependencies, dependencies).
+- Changing the editor selection prompt.
+
+## Acceptance Criteria
+1. The setup flow has one fewer prompt (no prepare script question).
+2. Installing always adds the prepare script to `package.json`.
+3. Uninstalling always removes the prepare script from `package.json`.
+4. Post-apply output includes actionable next-step messages for both install and uninstall flows.
+5. The project's validation workflow passes without regressions.

package/repos/tsgo/.specs/setup-unified-pipeline.md

@@ -0,0 +1,41 @@
+# Setup Command: Unified Change Pipeline
+
+## Goal
+Ensure the CLI `setup` command processes all file changes — including creation of new files — through a single, uniform pipeline: assess → compute changes → render diffs → confirm → apply. No file type should have a special-cased path in the orchestrator.
+
+## Scope
+- Applies to the setup command implementation in `_packages/tsgo/src/setup/`.
+- Covers the orchestrator (`index.ts`), change computation (`changes.ts`), diff rendering (`diff-renderer.ts`), and the shared types (`types.ts`).
+
+## Background
+The reference implementation (`effect-language-service`) treats all file modifications uniformly as code actions with text changes. When a file doesn't exist yet (e.g., `.vscode/settings.json`), it uses a generic `isNewFile` mechanism: the code action's file change carries the full content, and the apply phase creates the directory and writes the file.
+
+The current tsgo version deviates by special-casing VS Code settings creation: a separate `needsNewVSCodeSettings` flag, a dual exit condition, and a dedicated apply block that bypasses the change tracker, diff rendering, and user review.
+
+## Reference Implementation
+The canonical reference for this pattern lives in the `effect-language-service` repository (cloned at `.repos/effect-language-service`):
+
+- **Orchestrator & apply loop**: `.repos/effect-language-service/packages/language-service/src/cli/setup.ts` — lines 185–234 contain the generic apply loop with `isNewFile` handling (mkdir + write for new files, reverse-order text change application for existing files).
+- **Change computation**: `.repos/effect-language-service/packages/language-service/src/cli/setup/changes.ts` — `computeChanges()` aggregates changes and emits `{ fileName, textChanges, isNewFile }` for each file change.
+- **Diff rendering**: `.repos/effect-language-service/packages/language-service/src/cli/setup/diff-renderer.ts` — `renderCodeActions()` handles both existing and new files uniformly.
+
+## Requirements
+
+1. The code action data model must support a marker indicating that a file change represents a new file (not a modification to an existing file).
+2. When assessment detects that a target file does not exist but the user's target state requires it, `computeChanges()` must emit a code action with the new-file marker and the full file content as a text change — the same way it emits changes for existing files. Specifically: when the user selects a VS Code-based editor (VS Code, Cursor) and `.vscode/settings.json` does not exist, the pipeline must create it rather than silently skipping it.
+3. The diff renderer must handle new-file code actions by showing the entire file content as additions (all green / `+` lines), so the user can review new file content before confirming.
+4. The apply phase must handle new-file code actions generically: create the parent directory if needed and write the file content. This mechanism must not be specific to any single file type.
+5. The orchestrator (`index.ts`) must not contain file-type-specific flags, exit conditions, or apply blocks. All file changes flow through the same pipeline phases.
+6. User-visible behavior must remain equivalent: the same files are created/modified, the same prompts are shown, and the user can still review and confirm all changes before they are applied.
+
+## Non-Goals
+- Changing the assessment or target-prompt logic (what questions are asked, what options are available).
+- Adding support for deleting files through the pipeline.
+- Changing the diff rendering style or colors.
+
+## Acceptance Criteria
+1. Creating a new `.vscode/settings.json` (when the file doesn't exist) goes through the full pipeline: its content appears in the diff output, the user confirms, and then it's written.
+2. The orchestrator has no special-cased flags or apply blocks for specific file types.
+3. The apply loop handles both existing-file modifications and new-file creation through a single generic mechanism.
+4. All existing setup scenarios (update existing files, add new dependencies, remove LSP, etc.) continue to work identically.
+5. The project's validation workflow passes without regressions.

package/repos/tsgo/.specs/tsconfig-schema-generation.md

@@ -0,0 +1,46 @@
+# tsconfig JSON Schema Generation
+
+## Overview
+
+Generate a JSON Schema file (`schema.json` at the repo root) that extends the standard TypeScript `tsconfig.json` schema with the Effect Language Service plugin configuration. This gives editors (VS Code, etc.) autocomplete and validation for the `@effect/language-service` plugin entry inside `compilerOptions.plugins`.
+
+## Reference Implementation
+
+The JavaScript implementation added this in [Effect-TS/language-service#681](https://github.com/Effect-TS/language-service/commit/1017a5443b2e6919f18e57afb86373ba825037c9). Since our rule definitions and plugin options now live in Go, the generation must happen in Go as well.
+
+## Data Sources
+
+1. **`rules.All`** (from `internal/rules/rules.go`) — provides each rule's `Name`, `Description`, and `DefaultSeverity` for building the `diagnosticSeverity` property schema with per-rule entries and defaults.
+
+2. **`EffectPluginOptions` struct** (from `etscore/options.go`) — provides all other plugin property definitions (types, defaults, enums, descriptions). These are defined explicitly as JSON Schema fragments rather than reflected from struct tags, since descriptions and enum constraints are needed.
+
+3. **Upstream tsconfig schema reference** (`https://json.schemastore.org/tsconfig`) — the upstream TypeScript tsconfig schema that the generated document layers on top of via `allOf`.
+
+## Generated Output
+
+The generator produces a `schema.json` at the repo root. The schema extends the upstream tsconfig schema by constraining `compilerOptions.plugins.items` to an `anyOf` containing:
+
+- An Effect plugin schema object (with `name` constrained to `"@effect/language-service"` and all plugin-specific properties)
+- The original plugin schema (with a `not` constraint excluding the Effect plugin name)
+
+The `diagnosticSeverity` property is a dedicated definition (`effectLanguageServicePluginDiagnosticSeverityDefinition`) referenced via `$ref`, containing a property for each rule with its enum of severity values and the rule's default severity.
+
+## Baseline Test Pattern
+
+The test follows the same baseline pattern used elsewhere in the project:
+
+1. The test generates the schema in memory.
+2. It writes the result to `testdata/baselines/local/schema.json` using baseline logic — only writing if the content has actually changed.
+3. It compares the local baseline against the committed `schema.json` at the repo root (the reference copy).
+4. If they differ, the test fails.
+
+To update after a rule or option change, the developer runs the test (which updates the local baseline), then copies it to the repo root.
+
+No `go:generate` step is needed — the test is the source of truth.
+
+## Location
+
+- Generator function: `etscore/options_schema.go`
+- Schema comparison test: `etscore/options_schema_test.go`
+- Local baseline: `testdata/baselines/local/schema.json`
+- Reference (committed): `schema.json` (repo root)