@tslite/editor 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,773 @@
+import { TypeOverlay, Env } from '@tslite/checker';
+import { BaseNode } from '@tslite/core';
+import { DiagnosticHelp } from '@tslite/explain';
+
+/** Posição na convenção TSLite: linha 1-based, coluna 0-based. */
+interface EditorPosition {
+    readonly line: number;
+    readonly column: number;
+}
+/** Trecho `[start, end)` — fim exclusivo. */
+interface EditorRange {
+    readonly start: EditorPosition;
+    readonly end: EditorPosition;
+}
+/** Uma edição aplicável (o quick-fix). */
+interface EditorEdit {
+    readonly range: EditorRange;
+    readonly newText: string;
+}
+/**
+ * Um diagnóstico SEM posição — o nó não tem `loc` (AST de builders, não de texto).
+ * Não vira marker, mas continua sendo um erro real: mostre num painel. Carrega
+ * `severity` e `help` porque quem renderiza precisa dos dois tanto quanto no
+ * posicionado — só a coordenada falta.
+ */
+interface UnpositionedDiagnostic {
+    readonly code: string;
+    readonly message: string;
+    readonly severity: "error" | "warning";
+    readonly help?: DiagnosticHelp;
+}
+/**
+ * Marcas de diagnóstico — os mesmos valores no Monaco (`MarkerTag`) e no LSP
+ * (`DiagnosticTag`). Mudam como o trecho é RENDERIZADO, não a severidade.
+ */
+declare const DIAGNOSTIC_TAG: {
+    /** Código desnecessário → o editor o mostra **apagado** (opaco). */
+    readonly Unnecessary: 1;
+    /** Depreciado → riscado. */
+    readonly Deprecated: 2;
+};
+/**
+ * Os códigos cujo diagnóstico é "isto está sobrando", não "isto está errado".
+ * Fonte única do `tags` — os dois emissores só repassam.
+ */
+declare const UNNECESSARY_CODES: ReadonlySet<string>;
+/** Um diagnóstico já POSICIONADO, pronto pra virar marker/diagnostic. */
+interface EditorDiagnostic {
+    readonly range: EditorRange;
+    readonly message: string;
+    readonly severity: "error" | "warning";
+    readonly code: string;
+    /** Ajuda pedagógica (JS-isms) — vira o hover rico. */
+    readonly help?: DiagnosticHelp;
+    /** Correção mecânica aplicável — vira o code action. */
+    readonly edit?: EditorEdit;
+    /**
+     * Marcas de renderização (ver {@link DIAGNOSTIC_TAG}). O binding não-usado sai
+     * com `[1]` — é o que faz o editor APAGAR o trecho em vez de sublinhá-lo. Sem
+     * isto, "variável em desuso" viraria mais um squiggle amarelo no meio do código.
+     */
+    readonly tags?: readonly number[];
+}
+/**
+ * O resultado do `analyze`. `unpositioned` existe para que **nada seja perdido em
+ * silêncio**: um diagnóstico cujo nó não tem `loc` (AST vindo de builders, não de
+ * texto) não pode virar marker, mas continua sendo um erro real — mostre-o num
+ * painel. Se a fonte é texto, esta lista é sempre vazia.
+ */
+interface AnalyzeResult {
+    readonly diagnostics: readonly EditorDiagnostic[];
+    readonly unpositioned: readonly UnpositionedDiagnostic[];
+    /** `true` se o código nem parseou (só há um diagnóstico, o de sintaxe). */
+    readonly parseFailed: boolean;
+    /**
+     * AST + overlay do arquivo — habilita consultas por POSIÇÃO (`typeAtPosition`).
+     * Ausente quando não parseou.
+     *
+     * É objeto vivo e pesado (o `overlay` é um `WeakMap`): guarde-o, mas **leia de
+     * forma não-reativa**. Um componente que o selecione re-renderiza a cada análise
+     * sem precisar.
+     */
+    readonly program?: ProgramInfo;
+}
+/** O AST tipado de um arquivo — a entrada das consultas por posição. */
+interface ProgramInfo {
+    readonly ast: BaseNode;
+    readonly overlay: TypeOverlay;
+}
+/**
+ * Casa com `monaco.editor.IMarkerData`. Severidade: 8=Error, 4=Warning.
+ *
+ * `tags: [1]` (`MarkerTag.Unnecessary`) é o que faz o editor renderizar o trecho
+ * **APAGADO** em vez de sublinhado — é assim que "variável não usada" fica opaca
+ * no VSCode. Não é colorização: é o diagnóstico que carrega a marca.
+ */
+interface MonacoMarker {
+    readonly startLineNumber: number;
+    readonly startColumn: number;
+    readonly endLineNumber: number;
+    readonly endColumn: number;
+    readonly message: string;
+    readonly severity: number;
+    readonly code?: string;
+    readonly source?: string;
+    /** `1` = Unnecessary (apagado) · `2` = Deprecated (riscado). */
+    readonly tags?: readonly number[];
+}
+/**
+ * Casa com `vscode.Diagnostic` / LSP. Severidade: 1=Error, 2=Warning.
+ *
+ * `tags` usa os MESMOS valores do Monaco (`DiagnosticTag` do LSP: 1=Unnecessary,
+ * 2=Deprecated) — uma das raras coisas que não mudam de base entre os dois.
+ */
+interface LspDiagnostic {
+    readonly range: {
+        readonly start: {
+            readonly line: number;
+            readonly character: number;
+        };
+        readonly end: {
+            readonly line: number;
+            readonly character: number;
+        };
+    };
+    readonly message: string;
+    readonly severity: number;
+    readonly code?: string;
+    readonly source?: string;
+    /** `1` = Unnecessary (apagado) · `2` = Deprecated (riscado). */
+    readonly tags?: readonly number[];
+}
+/** Um quick-fix, na forma comum a Monaco (`CodeAction`) e LSP. */
+interface EditorCodeAction {
+    readonly title: string;
+    readonly kind: "quickfix";
+    readonly isPreferred: boolean;
+    /** O diagnóstico que esta ação corrige (mesmo range/código). */
+    readonly diagnostic: {
+        readonly code: string;
+        readonly message: string;
+    };
+    /** A edição — já na base do alvo (Monaco 1-based col; LSP 0-based line). */
+    readonly edit: {
+        readonly range: {
+            readonly startLineNumber: number;
+            readonly startColumn: number;
+            readonly endLineNumber: number;
+            readonly endColumn: number;
+        };
+        readonly text: string;
+    };
+}
+
+interface AnalyzeOptions {
+    /** `program` (default) ou `expression` (uma expressão solta, ex.: um mapper). */
+    readonly mode?: "program" | "expression";
+    /**
+     * Bindings declarados e nunca lidos (`unused-name`) — **ligado por default aqui**,
+     * ao contrário do `check`.
+     *
+     * Não é incoerência, é fidelidade: no tsc o `noUnusedLocals` vem desligado (o
+     * *compilador* não deve falhar por higiene), mas o **tsserver** reporta o não-usado
+     * como sugestão de qualquer forma — é por isso que o VSCode apaga a variável em
+     * desuso num `.ts` sem nenhum `tsconfig`. `analyze` é a API de EDITOR, então segue
+     * o editor; `check` é a do compilador, e segue o compilador.
+     *
+     * Passe `false` para desligar.
+     */
+    readonly unused?: boolean | {
+        readonly locals?: boolean;
+        readonly parameters?: boolean;
+    };
+}
+/**
+ * Analisa um trecho de código e devolve tudo que um editor precisa.
+ * **Nunca lança** — erro de sintaxe vira diagnóstico.
+ */
+declare function analyze(source: string, env: Env, opts?: AnalyzeOptions): AnalyzeResult;
+
+/** Markdown do hover: mensagem + o "por que NÃO é bug" + a sugestão + o fix. */
+declare function hoverMarkdown(d: EditorDiagnostic): string;
+
+/**
+ * Converte diagnósticos em markers do Monaco (o sublinhado vermelho).
+ *
+ * ```ts
+ * monaco.editor.setModelMarkers(model, "tslite", toMonacoMarkers(diags));
+ * ```
+ */
+declare function toMonacoMarkers(diagnostics: readonly EditorDiagnostic[], source?: string): MonacoMarker[];
+/**
+ * Os quick-fixes, na base do Monaco. Só existem para diagnósticos com `edit`
+ * (hoje: os JS-isms com operador equivalente — `arr.length` → `length(arr)`).
+ *
+ * ```ts
+ * monaco.languages.registerCodeActionProvider("tslite", {
+ *   provideCodeActions: (model) => ({
+ *     actions: toMonacoCodeActions(diags).map((a) => ({
+ *       title: a.title, kind: a.kind, isPreferred: a.isPreferred,
+ *       edit: { edits: [{ resource: model.uri, textEdit: { range: a.edit.range, text: a.edit.text }, versionId: undefined }] },
+ *     })),
+ *     dispose() {},
+ *   }),
+ * });
+ * ```
+ */
+declare function toMonacoCodeActions(diagnostics: readonly EditorDiagnostic[]): EditorCodeAction[];
+/**
+ * O conteúdo do hover (markdown) para uma posição do Monaco — recebe linha/coluna
+ * **na base do Monaco** e devolve o diagnóstico que cobre aquele ponto.
+ *
+ * ```ts
+ * monaco.languages.registerHoverProvider("tslite", {
+ *   provideHover: (_m, pos) => {
+ *     const h = monacoHoverAt(diags, pos.lineNumber, pos.column);
+ *     return h ? { contents: [{ value: h }] } : null;
+ *   },
+ * });
+ * ```
+ */
+declare function monacoHoverAt(diagnostics: readonly EditorDiagnostic[], lineNumber: number, column: number): string | undefined;
+
+/** Converte diagnósticos para a forma do LSP / `vscode.Diagnostic`. */
+declare function toLspDiagnostics(diagnostics: readonly EditorDiagnostic[], source?: string): LspDiagnostic[];
+/** Os quick-fixes na base do LSP (linha 0-based). */
+declare function toLspCodeActions(diagnostics: readonly EditorDiagnostic[]): EditorCodeAction[];
+/** O hover markdown na base do LSP (linha/char 0-based). */
+declare function lspHoverAt(diagnostics: readonly EditorDiagnostic[], line: number, character: number): string | undefined;
+
+/** O id da linguagem. Registre o modelo e os provedores neste id. */
+declare const TSLITE_LANGUAGE_ID = "tslite";
+/** Extensões que o editor deve associar à linguagem. */
+declare const TSLITE_EXTENSIONS: readonly [".ts", ".d.ts", ".tsl"];
+/**
+ * A gramática Monarch. Estrutura compatível com `monaco.languages.IMonarchLanguage`
+ * (tipada estruturalmente para não importar o monaco).
+ */
+declare const tsliteMonarchLanguage: {
+    defaultToken: string;
+    tokenPostfix: string;
+    keywords: ("undefined" | "type" | "in" | "typeof" | "void" | "delete" | "var" | "let" | "const" | "null" | "false" | "break" | "if" | "else" | "return" | "async" | "await" | "true" | "for" | "while" | "do" | "throw" | "try" | "catch" | "finally" | "switch" | "case" | "continue" | "default" | "import" | "export" | "extends" | "infer" | "of" | "keyof" | "as" | "from")[];
+    controlKeywords: ("break" | "if" | "else" | "return" | "await" | "for" | "while" | "do" | "throw" | "try" | "catch" | "finally" | "switch" | "case" | "continue" | "import" | "export" | "from")[];
+    literalKeywords: ("undefined" | "null" | "false" | "true")[];
+    forbidden: ("function" | "instanceof" | "class" | "new" | "this" | "yield" | "super" | "debugger" | "with")[];
+    typeKeywords: ("string" | "number" | "bigint" | "boolean" | "symbol" | "object" | "any" | "unknown" | "never")[];
+    operators: string[];
+    symbols: RegExp;
+    escapes: RegExp;
+    digits: RegExp;
+    tokenizer: {
+        root: ((string | RegExp)[] | {
+            include: string;
+        } | (RegExp | string[])[] | (RegExp | {
+            cases: {
+                "@controlKeywords": string;
+                "@keywords": string;
+                "@typeKeywords": string;
+                "@default": string;
+            };
+        })[] | (RegExp | {
+            cases: {
+                "@typeKeywords": string;
+                "@default": string;
+            };
+        })[] | (RegExp | {
+            cases: {
+                "@controlKeywords": string;
+                "@literalKeywords": string;
+                "@keywords": string;
+                "@typeKeywords": string;
+                "@default": string;
+            };
+        })[] | (RegExp | {
+            cases: {
+                "@operators": string;
+                "@default": string;
+            };
+        })[])[];
+        whitespace: (string | RegExp)[][];
+        comment: (string | RegExp)[][];
+        string_double: (string | RegExp)[][];
+        string_single: (string | RegExp)[][];
+        string_backtick: ((string | RegExp)[] | (RegExp | {
+            token: string;
+            next: string;
+        })[])[];
+        bracketCounting: ((string | RegExp)[] | {
+            include: string;
+        })[];
+    };
+};
+/**
+ * Configuração da linguagem: comentários, pares de brackets, auto-fechamento.
+ * Compatível com `monaco.languages.LanguageConfiguration`.
+ */
+declare const tsliteLanguageConfiguration: {
+    comments: {
+        lineComment: string;
+        blockComment: [string, string];
+    };
+    brackets: [string, string][];
+    autoClosingPairs: ({
+        open: string;
+        close: string;
+        notIn?: undefined;
+    } | {
+        open: string;
+        close: string;
+        notIn: string[];
+    })[];
+    surroundingPairs: {
+        open: string;
+        close: string;
+    }[];
+    folding: {
+        markers: {
+            start: RegExp;
+            end: RegExp;
+        };
+    };
+};
+/** Fiel ao VSCode Dark+ — a referência de "parece TypeScript". */
+declare const tsliteDarkPlusThemeRules: readonly [{
+    readonly token: "invalid";
+    readonly foreground: "f14c4c";
+    readonly fontStyle: "underline";
+}, {
+    readonly token: "string.invalid";
+    readonly foreground: "f14c4c";
+}, {
+    readonly token: "keyword";
+    readonly foreground: "569cd6";
+}, {
+    readonly token: "keyword.control";
+    readonly foreground: "c586c0";
+}, {
+    readonly token: "keyword.literal";
+    readonly foreground: "569cd6";
+}, {
+    readonly token: "type";
+    readonly foreground: "4ec9b0";
+}, {
+    readonly token: "type.identifier";
+    readonly foreground: "4ec9b0";
+}, {
+    readonly token: "function";
+    readonly foreground: "dcdcaa";
+}, {
+    readonly token: "function.member";
+    readonly foreground: "dcdcaa";
+}, {
+    readonly token: "property";
+    readonly foreground: "9cdcfe";
+}, {
+    readonly token: "property.declaration";
+    readonly foreground: "9cdcfe";
+}, {
+    readonly token: "identifier";
+    readonly foreground: "9cdcfe";
+}, {
+    readonly token: "variable";
+    readonly foreground: "9cdcfe";
+}, {
+    readonly token: "parameter";
+    readonly foreground: "9cdcfe";
+}, {
+    readonly token: "string";
+    readonly foreground: "ce9178";
+}, {
+    readonly token: "string.escape";
+    readonly foreground: "d7ba7d";
+}, {
+    readonly token: "number";
+    readonly foreground: "b5cea8";
+}, {
+    readonly token: "comment";
+    readonly foreground: "6a9955";
+    readonly fontStyle: "italic";
+}, {
+    readonly token: "operator";
+    readonly foreground: "d4d4d4";
+}, {
+    readonly token: "operator.arrow";
+    readonly foreground: "569cd6";
+}, {
+    readonly token: "delimiter";
+    readonly foreground: "d4d4d4";
+}];
+/**
+ * O DEFAULT: separação alta de papéis.
+ *
+ * O que muda em relação ao Dark+, e por quê — cada linha resolve um caso em que
+ * a tela escondia informação que o checker já tinha:
+ *
+ * | papel | aqui | no Dark+ |
+ * | --- | --- | --- |
+ * | parâmetro | laranja **itálico** | #9CDCFE (igual a tudo) |
+ * | chave de objeto (`cep:`) | ciano | #9CDCFE (igual ao valor) |
+ * | propriedade lida (`r.cep`) | cor de texto | #9CDCFE |
+ * | função | verde | amarelo |
+ * | tipo | ciano **itálico** | teal |
+ *
+ * Resultado prático: em `cep: r.cep`, a chave, o parâmetro e a propriedade
+ * ficam em três tons distintos — que era o ponto.
+ */
+declare const tsliteThemeRules: readonly [{
+    readonly token: "invalid";
+    readonly foreground: "ff5555";
+    readonly fontStyle: "underline";
+}, {
+    readonly token: "string.invalid";
+    readonly foreground: "ff5555";
+}, {
+    readonly token: "keyword";
+    readonly foreground: "ff79c6";
+}, {
+    readonly token: "keyword.control";
+    readonly foreground: "ff79c6";
+}, {
+    readonly token: "keyword.literal";
+    readonly foreground: "bd93f9";
+}, {
+    readonly token: "type";
+    readonly foreground: "8be9fd";
+    readonly fontStyle: "italic";
+}, {
+    readonly token: "type.identifier";
+    readonly foreground: "8be9fd";
+    readonly fontStyle: "italic";
+}, {
+    readonly token: "function";
+    readonly foreground: "50fa7b";
+}, {
+    readonly token: "function.member";
+    readonly foreground: "50fa7b";
+}, {
+    readonly token: "parameter";
+    readonly foreground: "ffb86c";
+    readonly fontStyle: "italic";
+}, {
+    readonly token: "property.declaration";
+    readonly foreground: "8be9fd";
+}, {
+    readonly token: "property";
+    readonly foreground: "f8f8f2";
+}, {
+    readonly token: "variable";
+    readonly foreground: "f8f8f2";
+}, {
+    readonly token: "identifier";
+    readonly foreground: "f8f8f2";
+}, {
+    readonly token: "string";
+    readonly foreground: "f1fa8c";
+}, {
+    readonly token: "string.escape";
+    readonly foreground: "ffb86c";
+}, {
+    readonly token: "number";
+    readonly foreground: "bd93f9";
+}, {
+    readonly token: "comment";
+    readonly foreground: "6272a4";
+    readonly fontStyle: "italic";
+}, {
+    readonly token: "operator";
+    readonly foreground: "ff79c6";
+}, {
+    readonly token: "operator.arrow";
+    readonly foreground: "ff79c6";
+}, {
+    readonly token: "delimiter";
+    readonly foreground: "f8f8f2";
+}];
+
+/**
+ * A legenda — a ORDEM define os índices usados na codificação. Um consumidor
+ * precisa registrar exatamente esta legenda, senão as cores saem trocadas.
+ *
+ * Subconjunto dos tipos padrão do protocolo (os que a Linguagem realmente tem:
+ * sem classe, sem enum, sem método).
+ */
+declare const TSLITE_SEMANTIC_LEGEND: {
+    readonly tokenTypes: readonly ["variable", "parameter", "property", "function", "type"];
+    readonly tokenModifiers: readonly ["declaration", "readonly", "defaultLibrary"];
+};
+type SemanticTokenType = (typeof TSLITE_SEMANTIC_LEGEND.tokenTypes)[number];
+type SemanticTokenModifier = (typeof TSLITE_SEMANTIC_LEGEND.tokenModifiers)[number];
+/** Um token semântico na convenção TSLite (linha 1-based, coluna 0-based). */
+interface SemanticToken {
+    readonly range: EditorRange;
+    readonly type: SemanticTokenType;
+    readonly modifiers: readonly SemanticTokenModifier[];
+}
+/**
+ * Os tokens semânticos do arquivo, na convenção TSLite (linha 1-based, coluna
+ * 0-based), ordenados por posição.
+ *
+ * **Limite conhecido** (o mesmo do hover de tipo, E6): uma **anotação de tipo**
+ * (`r: RawViaCep`) não é nó com `loc` — é `Schema` apagável no nó —, então o nome
+ * do tipo ali não recebe token semântico. Quem pinta esse caso é a heurística de
+ * capitalização da gramática Monarch. O nome de um `type X = …` (que É nó) recebe.
+ */
+declare function semanticTokensOf(program: ProgramInfo): SemanticToken[];
+/**
+ * Os tokens no formato de fio do protocolo: `Uint32Array` de quíntuplas
+ * `[deltaLine, deltaStart, length, tokenType, tokenModifiers]`, delta-encodadas.
+ *
+ * **Serve Monaco E LSP com o MESMO array** — o Monaco copiou o protocolo do LSP
+ * inteiro. É a exceção à regra dos dois emissores (E2), e a razão é justamente a
+ * que dita a regra: aqui as bases coincidem (**linha 0-based** nos dois), então
+ * um emissor só não esconde divergência nenhuma.
+ *
+ * Cuidado: `linha - 1` porque o TSLite é 1-based e este protocolo é 0-based —
+ * ao contrário dos markers do próprio Monaco, que são 1-based.
+ */
+declare function encodeSemanticTokens(tokens: readonly SemanticToken[]): Uint32Array;
+/**
+ * Atalho: do `program` direto ao que o provider do editor devolve.
+ *
+ * ```ts
+ * monaco.languages.registerDocumentSemanticTokensProvider(TSLITE_LANGUAGE_ID, {
+ *   getLegend: () => TSLITE_SEMANTIC_LEGEND,
+ *   provideDocumentSemanticTokens: () => semanticTokens(program),
+ *   releaseDocumentSemanticTokens: () => {},
+ * });
+ * ```
+ */
+declare function semanticTokens(program: ProgramInfo): {
+    data: Uint32Array;
+};
+
+/** Uma propriedade de um tipo objeto. */
+interface Prop {
+    readonly type: Schema;
+    /** `true` quando a propriedade pode estar ausente (`{ x?: T }`). */
+    readonly optional?: boolean;
+}
+/**
+ * Assinatura de índice de um objeto — `{ [k: string]: V }` (a forma de `Record<K, V>`).
+ * Coexiste com props nomeadas (`{ a: number; [k: string]: unknown }`), como no TS.
+ * O domínio da chave é só `string`/`number` (o que o TS permite).
+ */
+interface IndexSig {
+    readonly key: "string" | "number";
+    readonly value: Schema;
+}
+/**
+ * Flag de um elemento de tupla (espelha o `ElementFlags` do tsc):
+ * - `req` — elemento posicional normal (`A` em `[A, B]`);
+ * - `optional` — `A?` (pode estar ausente; `[A, B?]`); só TRAILING, posicional;
+ * - `rest` — `...T[]` (cauda de array); o tipo do elemento é o do array;
+ * - `variadic` — `...T` (spread de uma tupla/var); após `normalizeTuple` só var
+ *   genérica fica `variadic` (tupla concreta é espalhada; array vira `rest`).
+ */
+type ElementFlag = "req" | "optional" | "rest" | "variadic";
+/** Um parâmetro de um tipo função. */
+interface Param {
+    readonly name: string;
+    readonly type: Schema;
+    /** `true` quando o argumento pode ser omitido. */
+    readonly optional?: boolean;
+    /** `true` para o parâmetro rest (`...args: T[]`). */
+    readonly variadic?: boolean;
+}
+/**
+ * Type predicate `(v) => v is S` — quando a fn devolve `true`, o argumento na
+ * posição `param` é estreitado para `type` (S). `returns` da fn continua `boolean`
+ * (é o que roda); o `guard` é a info de narrowing. `filter`/`find` inferem S dele;
+ * `if (g(x))` estreita `x` (D13). Covariante em `type`.
+ */
+interface GuardSig {
+    readonly param: number;
+    readonly type: Schema;
+}
+/**
+ * O tipo de um valor na linguagem TSLite.
+ *
+ * O discriminador é `t`. Estruturas (object/array/union/fn) referenciam outros
+ * `Schema` recursivamente — inclusive de forma cíclica (ex.: `Node` que contém
+ * `Node[]`); as operações que percorrem `Schema` são cycle-safe.
+ */
+type Schema = {
+    readonly t: "any";
+} | {
+    readonly t: "unknown";
+} | {
+    readonly t: "string";
+} | {
+    readonly t: "number";
+} | {
+    readonly t: "boolean";
+} | {
+    readonly t: "null";
+} | {
+    readonly t: "undefined";
+} | {
+    readonly t: "void";
+} | {
+    readonly t: "literal";
+    readonly value: string | number | boolean;
+    /**
+     * `fresh` = literal "fresco" de uma EXPRESSÃO de valor (`1`, `"x"`) — alarga
+     * pra base em posição de membro (array/object/tupla) ou inferido num `T[]`,
+     * mas preserva no topo (`const x = 1` → `1`; `id(1)` → `1`). Literal de
+     * `keyof`/declarado é NÃO-fresh → nunca alarga. Transparente p/ subtype/equals.
+     */
+    readonly fresh?: boolean;
+} | {
+    readonly t: "object";
+    readonly props: Readonly<Record<string, Prop>>;
+    /** Assinatura de índice (`Record<K, V>`); coexiste com `props`. Ausente = objeto fechado. */
+    readonly index?: IndexSig;
+} | {
+    readonly t: "array";
+    readonly items: Schema;
+    /**
+     * `readonly T[]` (o `ReadonlyArray<T>` do TS). Só afeta a RELAÇÃO, e num
+     * sentido: `T[] ≤ readonly T[]`, mas **não** o contrário — dar um readonly
+     * onde se espera mutável perderia a garantia. TC28.
+     */
+    readonly readonly?: boolean;
+} | {
+    readonly t: "tuple";
+    readonly elements: readonly Schema[];
+    readonly flags?: readonly ElementFlag[];
+    /** `readonly [A, B]` — mesma regra do array readonly (TC28). */
+    readonly readonly?: boolean;
+} | {
+    readonly t: "union";
+    readonly of: readonly Schema[];
+} | {
+    readonly t: "fn";
+    readonly params: readonly Param[];
+    readonly returns: Schema;
+    /** Type predicate `(v) => v is S` — narrowing (ver `GuardSig`). */
+    readonly guard?: GuardSig;
+    /**
+     * Os type params **DECLARADOS**, em ordem (`<T, U>`). Ausente = a assinatura
+     * **não é genérica** — que é o que o tsc diz quando `Signature.typeParameters`
+     * é `undefined`.
+     *
+     * Existe para o **argumento de tipo explícito** (`f<T>(x)`): sem ordem
+     * declarada não dá para saber a que `var` o 1º argumento se liga, nem checar
+     * aridade. O tsc carrega exatamente isto (`types.ts#Signature.typeParameters`)
+     * e **nunca** deriva a ordem por aparição — sem a lista, ele trata a chamada
+     * como não-genérica e reporta TS2558. Fazemos igual (TC27).
+     *
+     * Só os NOMES: a constraint continua no próprio `var` (`var.bound`, TC10), que
+     * é onde o `sigBounds` já a procura. Defaults (`<T = string>`) estão fora do
+     * vocabulário, então "mínimo" ≡ "total" na checagem de aridade.
+     */
+    readonly typeParams?: readonly string[];
+} | {
+    readonly t: "overload";
+    readonly signatures: readonly {
+        readonly t: "fn";
+        readonly params: readonly Param[];
+        readonly returns: Schema;
+        readonly guard?: GuardSig;
+        /** Type params DECLARADOS desta assinatura (ver o `fn` acima). */
+        readonly typeParams?: readonly string[];
+    }[];
+} | {
+    readonly t: "keyof";
+    readonly of: Schema;
+} | {
+    readonly t: "index";
+    readonly obj: Schema;
+    readonly key: Schema;
+} | {
+    readonly t: "mapped";
+    readonly key: string;
+    readonly over: Schema;
+    readonly body: Schema;
+    readonly optional?: boolean;
+} | {
+    readonly t: "conditional";
+    readonly check: Schema;
+    readonly extends: Schema;
+    readonly then: Schema;
+    readonly else: Schema;
+    readonly infer?: readonly string[];
+} | {
+    readonly t: "intersection";
+    readonly of: readonly Schema[];
+} | {
+    readonly t: "returnType";
+    readonly fn: Schema;
+} | {
+    readonly t: "parameters";
+    readonly fn: Schema;
+} | {
+    readonly t: "var";
+    readonly name: string;
+    readonly bound?: Schema;
+    readonly isConst?: boolean;
+} | {
+    /**
+     * `typeof x` em posição de TIPO — o *type query* do TS.
+     *
+     * É o único nó do vocabulário que **não** se resolve pela álgebra: ele
+     * pergunta o tipo de um **VALOR**, e valor é assunto do escopo, que este
+     * package não conhece (zero-dep, por desenho). Quem resolve é o checker,
+     * no ponto de USO — espelhando o `getTypeFromTypeQueryNode` do tsc, que é
+     * lazy (`links.resolvedType`) pelo mesmo motivo.
+     *
+     * Um `typeQuery` que chegue à álgebra é sinal de que a resolução não
+     * aconteceu (nome inexistente — já reportado); os algoritmos o tratam como
+     * folha opaca, sem estourar.
+     */
+    readonly t: "typeQuery";
+    /** O entity name, em partes: `typeof obj.m` → `["obj", "m"]`. */
+    readonly path: readonly string[];
+} | {
+    readonly t: "apply";
+    readonly name: string;
+    readonly args: readonly Schema[];
+};
+
+/** O que o hover de tipo devolve. */
+interface TypeInfo {
+    /** O tipo formatado, estilo TS (`{ cep: string; uf: string }`). */
+    readonly text: string;
+    /**
+     * O que MOSTRAR no hover — o tipo em estilo **declaração** quando o nó é uma,
+     * como o VSCode faz (`const fn: () => number`, `type Res = number`,
+     * `(parameter) x: number`); igual a `text` no resto.
+     *
+     * Existe separado porque `text` é o TIPO (dado, comparável), e isto é
+     * APRESENTAÇÃO. Um consumidor que só quer o tipo continua lendo `text`.
+     */
+    readonly display: string;
+    /** O `Schema` cru — para quem quiser renderizar de outro jeito. */
+    readonly schema: Schema;
+    /** O tipo do nó ESTree que respondeu (`Identifier`, `CallExpression`, …). */
+    readonly nodeType: string;
+    /** O trecho coberto — para o editor destacar o que foi consultado. */
+    readonly range: EditorRange;
+}
+/** O nó mais interno que cobre a posição (convenção TSLite: coluna 0-based). */
+declare function nodeAt(ast: BaseNode, position: EditorPosition): BaseNode | undefined;
+/**
+ * O tipo sob a posição. `undefined` quando não há nó ali ou nenhum nó que a cobre
+ * foi tipado — o que é normal: pontuação e nós puramente estruturais não têm tipo.
+ *
+ * Sobe pelos ancestrais quando o nó mais interno não tem tipo (o cursor no `.` de
+ * `a.b`, por exemplo), para responder algo útil em vez de nada.
+ */
+declare function typeAtPosition(program: ProgramInfo, position: EditorPosition): TypeInfo | undefined;
+/** Onde um nome foi declarado — o que o Alt+clique do editor precisa. */
+interface DefinitionInfo {
+    /** O trecho da DECLARAÇÃO (convenção TSLite: linha 1-based, coluna 0-based). */
+    readonly range: EditorRange;
+    /** O nome resolvido — útil pra UI e pra teste. */
+    readonly name: string;
+    /**
+     * O que foi resolvido. `value` sai do binder (mesmo arquivo, sempre com
+     * `range`); `type` sai da tabela lateral de referências e pode estar em OUTRO
+     * arquivo — nesse caso o `range` é um placeholder e quem resolve é o consumidor,
+     * que é quem conhece o conjunto de arquivos. Ver `typeRefAt`.
+     */
+    readonly kind: "value" | "type";
+}
+/** O nome de TIPO sob a posição, se houver — a metade que o binder não vê. */
+declare function typeRefAt(program: ProgramInfo, position: EditorPosition): {
+    readonly name: string;
+    readonly range: EditorRange;
+} | undefined;
+declare function definitionAt(program: ProgramInfo, position: EditorPosition): DefinitionInfo | undefined;
+
+export { type AnalyzeOptions, type AnalyzeResult, DIAGNOSTIC_TAG, type DefinitionInfo, type EditorCodeAction, type EditorDiagnostic, type EditorEdit, type EditorPosition, type EditorRange, type LspDiagnostic, type MonacoMarker, type ProgramInfo, type SemanticToken, type SemanticTokenModifier, type SemanticTokenType, TSLITE_EXTENSIONS, TSLITE_LANGUAGE_ID, TSLITE_SEMANTIC_LEGEND, type TypeInfo, UNNECESSARY_CODES, type UnpositionedDiagnostic, analyze, definitionAt, encodeSemanticTokens, hoverMarkdown, lspHoverAt, monacoHoverAt, nodeAt, semanticTokens, semanticTokensOf, toLspCodeActions, toLspDiagnostics, toMonacoCodeActions, toMonacoMarkers, tsliteDarkPlusThemeRules, tsliteLanguageConfiguration, tsliteMonarchLanguage, tsliteThemeRules, typeAtPosition, typeRefAt };