@sayoriqwq/effect-harness 0.0.1 → 0.0.2

package/repos/tsgo/.specs/ast-navigation-utilities.md

@@ -0,0 +1,118 @@
+# AST Navigation Utilities Reference
+
+## Purpose
+
+This document catalogues the AST traversal and node-finding utilities available through the shim layer. All Effect code must import these from the shim packages (`shim/astnav`, `shim/ast`), never from `typescript-go` directly.
+
+## Token and Position Finding (`shim/astnav`)
+
+These functions locate tokens or nodes at specific character positions within a source file.
+
+| Function | Description |
+|----------|-------------|
+| **GetTokenAtPosition** | Returns the token at a position, including tokens in leading trivia. Creates synthesized tokens when needed and caches them. |
+| **GetTouchingToken** | Returns the token touching a position, excluding leading trivia. |
+| **GetTouchingPropertyName** | Gets the property name token at a position. Filters for property name literals, keywords, and private identifiers. |
+| **FindPrecedingToken** | Finds the rightmost valid token that precedes or touches the given position. |
+| **FindPrecedingTokenEx** | Extended version — allows starting from a specific node and optionally excluding JSDoc. |
+| **FindNextToken** | Finds the next token after a given token within a parent node. |
+| **FindChildOfKind** | Searches for a direct child node or token of a specified `ast.Kind` within a containing node. |
+| **GetStartOfNode** | Gets the start position of a node, with option to include or exclude JSDoc. |
+| **VisitEachChildAndJSDoc** | Visits each child of a node and its JSDoc comments with custom visitor callbacks. |
+
+## Ancestor and Hierarchy Navigation (`shim/ast`)
+
+These walk up the parent chain to find enclosing nodes that match a condition.
+
+| Function | Description |
+|----------|-------------|
+| **FindAncestor** | Walks up the parent chain, returns the first ancestor where the callback returns `true`. |
+| **FindAncestorKind** | Walks up the parent chain, returns the first ancestor matching a specific `ast.Kind`. |
+| **FindAncestorOrQuit** | Like `FindAncestor` but the callback can return `Quit` to abort the search early (useful when you know the target can't be further up). |
+
+## Container and Scope Finding (`shim/ast`)
+
+These find the enclosing function, class, or `this`-binding container for a node.
+
+| Function | Description |
+|----------|-------------|
+| **GetContainingFunction** | Finds the function declaration or expression containing the node. |
+| **GetContainingClass** | Finds the class declaration containing the node. |
+| **GetThisContainer** | Finds the container that defines the `this` binding. Options to include arrow functions and class computed property names. |
+| **GetSourceFileOfNode** | Walks up to the root `SourceFile`. |
+
+## Declaration and Binding Navigation (`shim/ast`)
+
+These navigate declaration structures — bindings, destructuring patterns, and names.
+
+| Function | Description |
+|----------|-------------|
+| **GetRootDeclaration** | For a `BindingElement`, traverses up through destructuring patterns to the root declaration. |
+| **GetNameOfDeclaration** | Gets the name node of any declaration (variable, function, class, parameter, etc.). |
+| **GetFirstIdentifier** | Recursively gets the leftmost identifier from a qualified name or property access chain (`a.b.c` → `a`). |
+| **WalkUpBindingElementsAndPatterns** | Walks up binding elements and destructuring patterns to the containing declaration. |
+| **FindConstructorDeclaration** | Finds the constructor declaration (with body) in a class. |
+
+## Expression Walking (`shim/ast`)
+
+These skip through wrapper nodes to reach the semantically meaningful expression or type.
+
+| Function | Description |
+|----------|-------------|
+| **WalkUpParenthesizedExpressions** | Walks up through `(expr)` wrappers to the containing expression. |
+| **WalkUpParenthesizedTypes** | Walks up through `(type)` wrappers to the containing type. |
+| **ClimbPastPropertyAccess** | From a property name in `a.b`, climbs to the outer property access expression. |
+
+## Call/Expression Target Checking (`shim/ast`)
+
+These check whether a node occupies a specific syntactic role (e.g., is it the thing being called?).
+
+| Function | Description |
+|----------|-------------|
+| **IsCallExpressionTarget** | Checks if a node is the target (callee) of a call expression. Options for element access and skipping outer expressions. |
+| **IsNewExpressionTarget** | Checks if a node is the target of a `new` expression. |
+| **IsCallOrNewExpressionTarget** | Combined check for call or new expression target. |
+| **IsTaggedTemplateTag** | Checks if a node is the tag of a tagged template expression. |
+| **IsDecoratorTarget** | Checks if a node is a decorator target. |
+| **IsJsxOpeningLikeElementTagName** | Checks if a node is the tag name of a JSX opening element. |
+
+## Traversal Iteration (`shim/ast`)
+
+These iterate over children or specific node types within a subtree.
+
+| Function | Description |
+|----------|-------------|
+| **ForEachChildAndJSDoc** | Iterates through each child of a node and its JSDoc comments using a `Visitor` callback. Return `true` to stop. |
+| **ForEachReturnStatement** | Finds and iterates all return statements within a function body, traversing into control flow structures. |
+| **ForEachDynamicImportOrRequireCall** | Iterates through all dynamic `import()` and `require()` calls in a source file. |
+
+## Node Methods (on `*ast.Node`)
+
+Every AST node exposes these traversal methods directly.
+
+| Method | Description |
+|--------|-------------|
+| **ForEachChild(visitor)** | Iterates children with a `Visitor` callback. Return `true` to stop. |
+| **VisitEachChild(visitor)** | Visits children with a `NodeVisitor`, allowing transformation. |
+| **IterChildren()** | Returns a Go iterator (`iter.Seq[*ast.Node]`) over the node's children. |
+| **Parent** | Field — the direct parent node (set during binding phase). |
+
+## Safe Casting Pattern
+
+When navigating AST nodes with `As*` methods, use a two-step guard pattern:
+
+1. Check shape first with `ast.Is*` (or an equivalent explicit `Kind`/nil guard).
+2. Cast second with `node.As*`.
+
+Rules and analyzers must avoid chained unchecked casts (for example, calling `As*` and immediately dereferencing fields in the same expression). If any expected shape check fails, fail closed for that candidate (skip and continue traversal) rather than panicking.
+
+## Visitor Patterns
+
+Two visitor patterns are available:
+
+- **`Visitor`** (`func(*ast.Node) bool`) — simple callback for read-only traversal. Return `true` to stop iteration.
+- **`NodeVisitor`** — structured visitor with hooks (`VisitNode`, `VisitToken`, `VisitNodes`, `VisitModifiers`) for AST transformation. Created via `NewNodeVisitor`.
+
+## Parent Binding
+
+- **`SetParentInChildren(node)`** — recursively sets the `Parent` pointer on all descendants. Must be called after creating or modifying AST nodes to ensure the parent chain is valid. All ancestor/container-finding utilities depend on this.

package/repos/tsgo/.specs/auto-import-style-overrides.md

@@ -0,0 +1,75 @@
+# Auto Import Style Overrides
+
+## Goal
+
+Allow users to configure auto-import style per package so Effect projects can choose between namespace-style imports and named imports from barrel packages.
+
+## Background
+
+The previous `effect-language-service` exposed package-scoped auto-import options and used them to rewrite import behavior for both completion-driven auto-imports and import-related quick fixes.
+
+In this TypeScript-Go fork, auto-imports for completions and import quick fixes already share a single core pipeline. This makes it possible to apply one consistent style policy in one place.
+
+## Scope
+
+- Porting the auto-import style option surface from the previous language service.
+- Parsing those options from `compilerOptions.plugins` into Effect plugin options.
+- Implementing style-rewrite behavior so completions and import quick fixes apply the configured import style consistently.
+- Defining where style logic should be injected so completions and import quick fixes stay consistent.
+
+## Requirements
+
+### Option Surface
+
+1. The Effect plugin option model must support package-scoped auto-import style controls:
+   - `namespaceImportPackages: string[]`
+   - `barrelImportPackages: string[]`
+   - `importAliases: Record<string, string>`
+   - `topLevelNamedReexports: "ignore" | "follow"`
+2. Default values:
+   - `namespaceImportPackages = []`
+   - `barrelImportPackages = []`
+   - `importAliases = {}`
+   - `topLevelNamedReexports = "ignore"`
+3. Package-name matching must be case-insensitive.
+
+### Option Parsing
+
+4. The options above must be parsed from the Effect plugin entry in `compilerOptions.plugins` and stored in Effect plugin options on compiler options.
+5. Invalid types must fall back to defaults rather than failing config parsing.
+6. Parsing coverage must include unit tests for defaults, valid inputs, and invalid-input fallback behavior.
+
+### Shared Injection Strategy
+
+7. Auto-import style policy must be applied in a single shared auto-import decision path used by:
+   - completion auto-import items
+   - import-related code fixes
+8. The implementation must avoid duplicating style logic separately in completion-specific and code-fix-specific wrappers.
+9. Any required usage-site text adjustment (for example, introducing a namespace qualifier when needed) must be produced through the same shared fix/edit pipeline so completion-resolve and code-fix application stay behaviorally aligned.
+
+### Workspace Consistency
+
+16. `typescript-go/` must be treated as resettable working state during checks; persistent changes must be represented through `_patches/`.
+17. If expected files under `typescript-go/` disappear or drift mid-implementation, the implementation flow must restore from git/submodule state and continue via patches, rather than relying on direct workspace edits as source of truth.
+
+### Style-Rewrite Behavior
+
+10. The configured package style options must affect generated auto-import edits, not only option parsing.
+11. For packages matched by `namespaceImportPackages`, generated auto-imports should prefer namespace-style imports and apply any required usage-site qualifier updates.
+12. For packages matched by `barrelImportPackages`, generated auto-imports should prefer named imports from the configured barrel resolution path.
+13. `importAliases` must be applied when generating import clauses and any introduced usage-site qualifier text.
+14. `topLevelNamedReexports` must control whether top-level named reexports are ignored or followed when choosing the import target.
+15. Completion-triggered auto-import edits and import-related code-fix edits must produce consistent results for the same symbol and config.
+
+## Non-Goals
+
+- Defining new style modes beyond the option surface listed above.
+
+## Acceptance Criteria
+
+1. The Effect plugin config can express package-scoped auto-import style overrides using the options in this spec.
+2. Parsed options are available in the Effect plugin options object with the documented defaults.
+3. Auto-import behavior (completion and code-fix flows) reflects configured namespace/barrel/alias/reexport style settings.
+4. Completion-triggered auto-import edits and import-related code-fix edits remain consistent under the same configuration.
+5. README plugin-options documentation includes the new options when they are shipped.
+6. The architecture for style injection is explicitly anchored to one shared auto-import pipeline so completions and import code fixes remain consistent.

package/repos/tsgo/.specs/cli-platform-filesystem.md

@@ -0,0 +1,24 @@
+# CLI Platform Filesystem and Path Usage
+
+## Goal
+Ensure the TypeScript-Go CLI entrypoint in this project uses Effect Platform abstractions for filesystem and path behavior, rather than direct Node built-ins.
+
+## Scope
+- Applies to the language-service TypeScript-Go CLI behavior currently defined in `_packages/tsgo/src/cli.ts`.
+- Covers all filesystem reads/writes/checks and path composition/normalization performed by the CLI.
+
+## Requirements
+1. CLI-visible behavior remains equivalent for users (inputs, outputs, error conditions, and exit behavior) after the change.
+2. Filesystem interactions must be expressed through Effect Platform filesystem capabilities.
+3. Path handling must be expressed through Effect Platform path capabilities.
+4. The CLI must not depend on direct `node:fs` imports for its operational behavior.
+5. The change must remain compatible with the project architecture rule that prefers Effect and shim-based integration boundaries.
+
+## Non-Goals
+- Introducing new CLI flags or changing documented CLI semantics.
+- Expanding this requirement to unrelated packages unless explicitly requested.
+
+## Acceptance Criteria
+1. CLI commands complete the same workflows as before for valid and invalid inputs.
+2. Filesystem/path-dependent flows continue to produce equivalent user-facing diagnostics and errors.
+3. Runtime behavior is validated by the project’s required validation workflow with no regressions.

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

@@ -0,0 +1,105 @@
+# Completion Infrastructure
+
+## Goal
+Add custom Effect completions support to the Go language service, following the same abstraction pattern used by rules, fixables, and refactors.
+
+## Background
+
+### Current state
+No custom completions exist in the Go version. The completion pipeline goes straight from TypeScript-Go's `ProvideCompletion()` (in `typescript-go/internal/ls/completions.go`) to the LSP client with no Effect customization point. No patches in `_patches/` touch completions.
+
+### Reference implementation
+The reference (`effect-language-service`) has 14 custom completions that hook into TypeScript's `getCompletionsAtPosition` via a proxy, run each completion definition's `apply()` function, and merge results with native completions.
+
+Key reference files:
+- Registry: `.repos/effect-language-service/packages/language-service/src/completions.ts`
+- Individual completions: `.repos/effect-language-service/packages/language-service/src/completions/*.ts` (14 files)
+- Core interface: `.repos/effect-language-service/packages/language-service/src/core/LSP.ts` (lines 109-139)
+- Tests: `.repos/effect-language-service/packages/language-service/test/completions.test.ts`
+
+### Auto-import middleware
+The reference has a `middlewareAutoImports.ts` that post-processes completions for auto-import support. This is **not needed** in the Go version — auto-completion is handled differently.
+
+## Existing Hook Patterns
+
+The codebase has three established abstraction layers that completions should mirror:
+
+| Abstraction | Struct | Context | Registry | Hook |
+|---|---|---|---|---|
+| **Rule** | `internal/rule/rule.go` | `rule.Context` (checker, sourceFile, severity) | `internal/rules/rules.go` → `All` slice | `RegisterAfterCheckSourceFileCallback` |
+| **Fixable** | `internal/fixable/fixable.go` | `fixable.Context` (checker via `GetTypeCheckerForFile`, span, errorCode) | `internal/fixables/fixables.go` → `All` slice | `RegisterCodeFixProvider` |
+| **Refactor** | `internal/refactor/refactor.go` | `refactor.Context` (checker via `GetTypeCheckerForFile`, span) | `internal/refactors/refactors.go` → `All` slice | `RegisterRefactorProvider` |
+
+All three follow the same shape:
+1. A struct with `Name`, `Description`, and a `Run` function
+2. A context type providing checker access, source file, and request-specific data
+3. A registry (`All` slice) with lookup helpers
+4. A hook registered in `etslshooks/init.go` that dispatches to all registered instances
+
+## Design
+
+### Naming
+The abstraction is called **"completion"** (singular for the type, plural `completions` for the registry package) — consistent with rule/rules, fixable/fixables, refactor/refactors.
+
+### File structure
+
+| Component | Path | Purpose |
+|---|---|---|
+| Struct definition | `internal/completion/completion.go` | `Completion` struct: `Name`, `Description`, `Run func(ctx *Context) []CompletionEntry` |
+| Context | `internal/completion/context.go` | Checker (from `Program.GetTypeChecker(ctx)`), source file, position, existing completion list |
+| Registry | `internal/completions/completions.go` | `All` slice, helper functions |
+| Implementations | `internal/completions/*.go` | One file per completion |
+| Registration | `etslshooks/init.go` | Hook registration alongside existing hooks |
+
+### Checker access
+The checker should be obtained via `Program.GetTypeChecker(ctx)`:
+```go
+func (p *Program) GetTypeChecker(ctx context.Context) (*checker.Checker, func()) {
+    return p.checkerPool.GetChecker(ctx)
+}
+```
+This matches how fixables and refactors access the checker through `GetTypeCheckerForFile`.
+
+### Hook pattern
+The "after callback" pattern (like hover and inlay hints) is the best fit:
+- An `AfterCompletionCallback` receives position, source file, and the existing completion list
+- The Effect layer iterates `completions.All`, runs each, and merges results into the existing list
+- This allows appending custom entries to the native completion list
+
+This differs from the "provider" pattern (used by fixables/refactors) because completions need access to the existing completion list to avoid duplicates.
+
+### Injection points in TypeScript-Go
+1. **`typescript-go/internal/ls/completions.go`** — Add `AfterCompletionCallback` variable, call it at the end of `ProvideCompletion()` before returning
+2. **`shim/ls/shim.go`** — Expose `RegisterAfterCompletionCallback` via `//go:linkname`
+3. **A new patch in `_patches/`** — To add the callback to the TypeScript-Go submodule (following the pattern of `012-ls-hover.patch` and `015-ls-inlay-hints.patch`)
+
+## Completions to Port
+
+### V4-compatible (higher priority)
+
+| Completion | Trigger | Needs Checker | Reference file |
+|---|---|---|---|
+| `effectSchemaSelfInClasses` | Extending Schema.Class, TaggedErrorClass, etc. | No (AST) | `completions/effectSchemaSelfInClasses.ts` |
+| `effectDataClasses` | Extending Data.TaggedError, TaggedClass | No (AST) | `completions/effectDataClasses.ts` |
+| `serviceMapSelfInClasses` | Extending ServiceMap.Service (V4 only) | No (AST) | `completions/serviceMapSelfInClasses.ts` |
+| `genFunctionStar` | Dot-accessing `.gen` | Yes | `completions/genFunctionStar.ts` |
+| `fnFunctionStar` | Dot-accessing `.fn` | No (AST) | `completions/fnFunctionStar.ts` |
+| `effectDiagnosticsComment` | `@effect-diagnostics` in comments | No (regex) | `completions/effectDiagnosticsComment.ts` |
+| `effectCodegensComment` | `@effect-codegens` in comments | No (regex) | `completions/effectCodegensComment.ts` |
+| `effectJsdocComment` | `@effect-identifier` in comments | No (regex) | `completions/effectJsdocComment.ts` |
+| `durationInput` | String literal with Duration contextual type | Yes | `completions/durationInput.ts` |
+
+### V3-only (lower priority)
+
+| Completion | Trigger | Needs Checker | Reference file |
+|---|---|---|---|
+| `contextSelfInClasses` | Extending Context.Tag | No (AST) | `completions/contextSelfInClasses.ts` |
+| `effectSelfInClasses` | Extending Effect.Service or Effect.Tag | No (AST) | `completions/effectSelfInClasses.ts` |
+| `effectSqlModelSelfInClasses` | Extending `@effect/sql` Model.Class | No (AST) | `completions/effectSqlModelSelfInClasses.ts` |
+| `rpcMakeClasses` | Extending `@effect/rpc` Rpc | No (AST) | `completions/rpcMakeClasses.ts` |
+| `schemaBrand` | Dot-accessing Schema for `.brand()` | No (AST) | `completions/schemaBrand.ts` |
+
+## Non-Goals
+- Auto-import post-processing middleware (handled differently in the Go version).
+- Changing TypeScript-Go's native completion behavior.
+- Completion sorting/priority beyond what TypeScript-Go provides natively.

package/repos/tsgo/.specs/deterministic-keys.md

@@ -0,0 +1,138 @@
+# deterministicKeys Rule
+
+## Overview
+
+The `deterministicKeys` rule ensures that string key literals passed to Effect service/tag/error class constructors follow a deterministic, location-based naming convention. When enabled, it compares the actual key string against an expected key computed from the class name, file path, and package name — and reports a diagnostic when they differ.
+
+This rule is **off by default** and must be explicitly enabled (e.g., via `// @effect-diagnostics deterministicKeys:error`).
+
+## Matched Patterns
+
+The rule walks every class declaration and tries to match it against these constructor patterns:
+
+| Pattern | V3 | V4 | Target | Example |
+|---------|----|----|--------|---------|
+| `Effect.Service<Self>()(key, options)` | ✅ | ❌ | `service` | `class Foo extends Effect.Service<Foo>()("key", { ... }) {}` |
+| `ServiceMap.Service<Self, Shape>()(key)` | ❌ | ✅ | `service` | `class Foo extends ServiceMap.Service<Foo, Shape>()("key") {}` |
+| `Context.Tag(key)<Self, Shape>()` | ✅ | ❌ | `service` | `class Foo extends Context.Tag("key")<Foo, Shape>() {}` |
+| `Effect.Tag(key)<Self, Shape>()` | ✅ | ❌ | `service` | `class Foo extends Effect.Tag("key")<Foo, Shape>() {}` |
+| `Data.TaggedError(key)<Fields>` | ✅ | ✅ | `error` | `class Foo extends Data.TaggedError("key")<{ msg: string }> {}` |
+| `Schema.TaggedError<Self>(key)(tag, fields)` | ✅ | ❌ | `error` | `class Foo extends Schema.TaggedError<Foo>("key")("tag", {}) {}` |
+| Custom (`@effect-identifier` annotation) | ✅ | ✅ | `custom` | Any constructor with `/** @effect-identifier */` parameter annotation |
+
+For each matched class, the rule extracts the class name, the key string literal, and the target category (`"service"`, `"error"`, or `"custom"`).
+
+The `custom` target is only active when the `extendedKeyDetection` option is enabled.
+
+## Key Builder Module
+
+The KeyBuilder module computes expected key strings from class metadata and source file location. It requires:
+
+- **Package name**: from the nearest `package.json`'s `name` field (already available via `typeparser.PackageJsonForSourceFile`)
+- **Package directory**: the directory containing that `package.json` (available via source file metadata's `PackageJsonDirectory`)
+- **File path**: the source file's full path
+- **Class name**: the declared class identifier
+
+### Key Patterns
+
+The key builder iterates over the configured `keyPatterns` list, matching on the `target` field (`"service"`, `"error"`, or `"custom"`). The first pattern whose target matches the class's target category is used.
+
+Three pattern formulas are supported:
+
+1. **`default`** (the standard pattern):
+   `<packageName>/<subDirectory>/<fileName>/<className>`
+   - Sub-directory is the file's directory relative to the package root, with configurable leading prefixes stripped (default: `["src/"]`)
+   - If the class name matches the file name (case-insensitive), the class name segment is omitted
+   - `index` file names are stripped
+   - Example: `@effect/myapp/services/AuthService`
+
+2. **`package-identifier`**:
+   `<packageName>/<fileName>/<className>`
+   - Same as `default` but omits the sub-directory segment entirely
+   - Example: `@effect/myapp/AuthService`
+
+3. **`default-hashed`**:
+   - Computes the same key as `default`, then hashes it with cyrb53 (a fast non-cryptographic hash producing a 16-character hex string)
+   - Example: `fc438e0396fbb4f7`
+
+### cyrb53 Hash
+
+The hash function used for `default-hashed` is cyrb53: a fast, non-cryptographic string hash that produces two 32-bit halves, output as a 16-character zero-padded hex string. The reference implementation is in `.repos/effect-language-service/packages/language-service/src/core/LSP.ts` (line 530).
+
+## Plugin Options
+
+The `deterministicKeys` rule depends on plugin options that must be parsed from the `compilerOptions.plugins` configuration in `tsconfig.json`. The following options are needed:
+
+### `keyPatterns`
+
+An array of key pattern objects, each with:
+- `target`: `"service"` | `"error"` | `"custom"` (default: `"service"`)
+- `pattern`: `"default"` | `"package-identifier"` | `"default-hashed"` (default: `"default"`)
+- `skipLeadingPath`: array of path prefixes to strip from the sub-directory (default: `["src/"]`)
+
+Default value:
+```json
+[
+  { "target": "service", "pattern": "default", "skipLeadingPath": ["src/"] },
+  { "target": "custom",  "pattern": "default", "skipLeadingPath": ["src/"] }
+]
+```
+
+Note: by default there is no pattern for `"error"` targets — error keys are only validated when the user explicitly adds an `"error"` pattern.
+
+### `extendedKeyDetection`
+
+A boolean (default: `false`). When enabled, the rule also matches constructors whose parameter is annotated with `/** @effect-identifier */` JSDoc, using the `"custom"` target category.
+
+### Current State of Plugin Options
+
+`EffectPluginOptions` (in `etscore/options.go`) currently parses only `diagnosticSeverity`, `ignoreEffectSuggestionsInTscExitCode`, and `ignoreEffectWarningsInTscExitCode`. It needs to be extended with `keyPatterns` and `extendedKeyDetection` fields, along with their parsing logic in `etscore/parser.go`.
+
+The full set of language service plugin options from the reference implementation is documented in `.repos/effect-language-service/packages/language-service/src/core/LanguageServicePluginOptions.ts`. Only the options relevant to ported rules need to be added.
+
+## Diagnostic
+
+When the actual key does not match the expected key, the rule reports:
+
+> Key should be '`<expectedKey>`'
+
+with rule name `effect(deterministicKeys)`.
+
+A new diagnostic message must be added to `internal/diagnostics/effectDiagnosticMessages.json`, followed by `pnpm setup-repo` to regenerate the diagnostic code.
+
+## Code Fix
+
+A quick fix (`deterministicKeys_fix`) replaces the incorrect key string literal with the expected key.
+
+## Reference Implementation
+
+The TypeScript reference implementation is in:
+- Rule: `.repos/effect-language-service/packages/language-service/src/diagnostics/deterministicKeys.ts`
+- Key builder: `.repos/effect-language-service/packages/language-service/src/core/KeyBuilder.ts`
+- Plugin options: `.repos/effect-language-service/packages/language-service/src/core/LanguageServicePluginOptions.ts`
+- cyrb53 hash: `.repos/effect-language-service/packages/language-service/src/core/LSP.ts` (line 530)
+
+## Type Parser Dependencies
+
+The rule requires the following type parser helpers to return the **key string literal** node (in addition to class name and self type):
+
+- `ExtendsContextTag` — exists, needs to expose key
+- `ExtendsEffectTag` — exists, needs to expose key
+- `ExtendsServiceMapService` — exists, needs to expose key
+- `ExtendsEffectService` — exists, needs to expose key
+- `ExtendsSchemaTaggedError` — exists, already exposes `KeyStringLiteral`
+- `ExtendsDataTaggedError` — does not exist, needs to be created
+- `PackageJsonForSourceFile` — exists, provides package name and directory
+
+## Tests
+
+Test fixtures should be ported from the reference language service for both V3 and V4:
+
+- `.repos/effect-language-service/packages/harness-effect-v4/examples/diagnostics/deterministicKeys.ts`
+- `.repos/effect-language-service/packages/harness-effect-v4/examples/diagnostics/deterministicKeys_defaultHashed.ts`
+- `.repos/effect-language-service/packages/harness-effect-v4/examples/diagnostics/deterministicKeys_packageIdentifier.ts`
+- `.repos/effect-language-service/packages/harness-effect-v4/examples/diagnostics/deterministicKeys_custom.ts`
+- `.repos/effect-language-service/packages/harness-effect-v3/examples/diagnostics/deterministicKeys.ts`
+- `.repos/effect-language-service/packages/harness-effect-v3/examples/diagnostics/deterministicKeys_defaultHashed.ts`
+- `.repos/effect-language-service/packages/harness-effect-v3/examples/diagnostics/deterministicKeys_packageIdentifier.ts`
+- `.repos/effect-language-service/packages/harness-effect-v3/examples/diagnostics/deterministicKeys_custom.ts`

package/repos/tsgo/.specs/diagnostic-metadata-generation.md

@@ -0,0 +1,131 @@
+# Diagnostic Metadata Generation
+
+## Goal
+
+Introduce a generated diagnostic metadata document for the tsgo implementation that matches the role and shape of the upstream `metadata.json`, so that diagnostic metadata is centralized, grouped, and consumed consistently by the setup flow and related tooling.
+
+## Scope
+
+- Covers generated diagnostic metadata for the tsgo language service package.
+- Covers the metadata filename rename from `rules.json` to `metadata.json`.
+- Covers metadata parity for existing rules that already exist in this repository.
+- Covers generated diagnostic preset metadata in that same document.
+- Covers generation of the root README diagnostics table from diagnostic metadata.
+- Covers the baseline test pattern that generates a local reference copy and compares it against the committed package copy.
+- Does not cover generating diagnostic preview payloads inside metadata; that is tracked separately.
+
+## Reference Source of Truth
+
+The canonical source for rule grouping values is the upstream `effect-language-service` repository in `.repos/effect-language-service`.
+
+For every diagnostic rule that exists in both repositories, the tsgo metadata must use the same group value as the upstream reference repository. The mapping must be copied rule-by-rule rather than inferred loosely.
+
+The upstream generation entrypoint for this metadata-and-README flow lives in:
+
+- `.repos/effect-language-service/packages/language-service/scripts/codegen.ts`
+- `.repos/effect-language-service/packages/language-service/test/metadata.test.ts`
+
+Those files are the primary references for how grouped metadata and the generated README diagnostics table are derived from rule metadata in the reference implementation, including the expected rule ordering.
+
+## Required Metadata Shape
+
+The generated metadata document must be named `metadata.json`.
+
+The generated document must include:
+
+- A top-level list of diagnostic groups with stable identifiers and their human-readable metadata.
+- A top-level list of diagnostic presets.
+- A top-level list of rules.
+- For each rule, metadata sufficient for setup and documentation consumers to reason about the rule without hardcoding separate tables.
+
+Each generated diagnostic preset entry must include at least:
+
+- Preset name
+- Preset description
+- The preset's `diagnosticSeverity` map
+
+Diagnostic presets must be generated by Go-side project sources in this repository rather than maintained manually in the committed `metadata.json`.
+
+When a tsgo preset intentionally mirrors an upstream preset, the generated metadata shape and preset semantics should stay aligned with upstream while still being derived from tsgo's local rule catalog and group metadata.
+
+For each rule that exists in tsgo, the metadata entry must include at least:
+
+- Rule name
+- Group
+- Description
+- Default severity
+
+If the current tsgo metadata document already carries additional fields that remain useful to existing consumers, they may remain present as long as the generated file is renamed to `metadata.json` and the data model is updated to include group information in the same overall role as the upstream reference.
+
+## Parity Requirements
+
+1. Every existing tsgo rule must appear in the generated `metadata.json`.
+2. Every rule that has an upstream counterpart must use the same group value as upstream.
+3. The metadata filename used by consumers must be `metadata.json`, not `rules.json`.
+4. Code that currently reads `rules.json` must instead read `metadata.json`.
+5. The committed metadata file in the package source tree must reflect the generated output exactly.
+6. Generated metadata rules must be ordered first by diagnostic group order and then by rule name within each group, matching the upstream reference behavior.
+7. Generated metadata presets must be present whenever tsgo exposes setup presets, and they must be derived from Go-side generation rather than handwritten JSON.
+8. Preset entries must be ordered deterministically so baseline output remains stable.
+
+## README Diagnostics Table
+
+The root `README.md` must contain markers that identify the generated diagnostics table section.
+
+The diagnostics table inside that marked section must be generated from diagnostic metadata rather than maintained manually.
+
+The generated table must match the same grouped shape used by the upstream `effect-language-service` implementation, including:
+
+- Grouped diagnostic sections
+- The same table structure and ordering model
+- Rule rows derived from metadata rather than handwritten README content
+
+This keeps documentation aligned with the generated metadata and avoids the rule list drifting from the actual source of truth.
+
+## Testing and Reference Copy
+
+The project must have a test that validates the generated metadata against a committed reference copy.
+
+The test flow must follow this pattern for metadata:
+
+1. Generate the metadata in memory.
+2. Write the generated result to a local baseline file under `testdata/baselines/local/`.
+3. Compare that local baseline file against the committed `metadata.json` that lives in the package source tree.
+4. Fail when the generated baseline and the committed reference file differ.
+
+The project must also have a test that validates the generated README diagnostics table against the committed repository README.
+
+The README test flow must follow this pattern:
+
+1. Read the committed root `README.md`, including the markers that bound the generated diagnostics table section.
+2. Generate the diagnostics table from rule metadata and splice it into the marked section.
+3. Write the generated README result to a local baseline file under `testdata/baselines/local/`.
+4. Compare that local generated README against the committed root `README.md`.
+5. Fail when the generated baseline and the committed README differ.
+
+Both tests must follow the existing baseline/reference approach so that generated metadata and generated documentation remain intentional and reviewable.
+
+## Non-Goals
+
+- Changing diagnostic behavior, emitted diagnostics, or quick-fix behavior.
+- Introducing new rules solely as part of this work.
+- Redesigning setup UX beyond switching it to the renamed and enriched metadata source.
+- Defining new grouping semantics that diverge from the upstream reference repository.
+- Requiring manual editing of the generated diagnostics table contents inside the README.
+- Generating or validating per-rule preview source text and preview diagnostic spans inside `metadata.json`.
+- Defining the setup prompt behavior that consumes presets; that is tracked separately from metadata generation.
+
+## Acceptance Criteria
+
+1. The generated diagnostics metadata file is named `metadata.json`.
+2. Existing tsgo consumers load `metadata.json` instead of `rules.json`.
+3. Every tsgo rule has a group value in generated metadata.
+4. For rules shared with upstream, the group value matches the upstream reference repository exactly.
+5. Generated metadata rules are ordered by group index first and by rule name second, matching the upstream reference behavior.
+6. The metadata comparison test writes a local baseline and compares it with the committed package `metadata.json`.
+7. The root README diagnostics table is generated from metadata within the README marker section and matches the grouped upstream shape.
+8. The README comparison test writes a local generated README baseline and compares it with the committed root `README.md`.
+9. The committed package `metadata.json` and committed root `README.md` can both be regenerated from project sources without manual editing of generated content.
+10. The generated `metadata.json` includes a top-level `presets` collection when tsgo exposes diagnostic presets.
+11. Each generated preset includes its name, description, and `diagnosticSeverity` map in the upstream-compatible metadata shape.
+12. Preset metadata is generated from Go-side repository sources rather than manually curated JSON.