@zern/tsls/README.md

TypeScript Language Service plugin for Zern Kernel virtual type augmentations

# @kernel/ts-ls

TypeScript Language Service plugin that generates Zern Kernel type augmentations in memory to power autocomplete and payload inference for events, alerts, and hooks without writing files to disk during development.

What it does

- Scans your source for declarative specs:
  - events: `createEvents('ns', { login: event<Payload>() })`
  - alerts: `createAlerts('ui', { Info: defineAlert<Payload>() })`
  - hooks: `createHooks('ns', { beforeLogin: defineHook<Payload>() })`
- Builds a virtual declaration file with module augmentations:
  - `declare module '@events/types' { interface ZernEvents { ... } }`
  - `declare module '@alerts/types' { interface ZernAlerts { ... } }`
  - `declare module '@hooks/types'  { interface ZernHooks  { ... } }`
- Serves this `.d.ts` from memory to the TS server so your editor gets:
  - autocomplete for `useEvents()/useAlerts()/useHooks()` sem argumentos
  - payload inference em `on/emit`

Install

```bash
npm i -D @kernel/ts-ls
# or
pnpm add -D @kernel/ts-ls
```

Usage (tsconfig.json)

```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@kernel/ts-ls",
        "pluginGlobs": ["**/*.plugin.ts", "plugins/**/specs/*.ts", "src/**/specs/*.{ts,tsx}"]
      }
    ]
  }
}
```

Options

- pluginGlobs: string[]
  - Globs para localizar arquivos que contém `createEvents/createAlerts/createHooks`.
  - Padrões padrão: `['**/*.plugin.ts', 'plugins/**/specs/*.ts', 'src/**/specs/*.{ts,tsx}']`.

Notes

- Dev-time only: o arquivo `.d.ts` é virtual (não é escrito em disco).
- Build/publish: gere um `.d.ts` físico no build do seu pacote para consumidores sem o plugin. Ex.: um passo de build que materializa `zern-augmentations.d.ts` (fora do escopo deste pacote).

How it detects payload types

- Tenta capturar `<Payload>` de `event<Payload>()`, `defineAlert<Payload>()`, `defineHook<Payload>()` via heurística simples de regex.
- Se não encontrar, usa `unknown` para aquele item (autocomplete funciona; inferência de payload vira `unknown`).

License
MIT