rooklang 0.3.3 → 0.4.0

package/README.md

@@ -25,14 +25,21 @@ close(jobs)
 for let i = 0; i < 4; i++ {
     console.log(<-results)
 }
+close(results)
 ```
 
 - **Goroutines and channels.** `go f(x)` runs a function as a goroutine, on another processor, and
-  channels, `select`, `after`, `tick` and `cancel` work as in Go; `go for i, v in pixels { ... }`
+  channels, `select`, `after`, `tick` and `cancel` work as in Go, and signals and `AbortSignal`
+  are channels too, `signal("SIGTERM")` and `done(request.signal)`; `go for i, v in pixels { ... }`
   splits an array among the processors. The compiler checks that what goes to another thread can be
-  copied there.
-- **Go syntax.** `func`, the type after the name, several results, errors as a second value,
-  `defer`, a single `for` loop:
+  copied there, and warns of a channel that is never closed; an instance of a `data class` goes
+  with its class and methods.
+- **Topics between tabs.** `topic<CartEvent>("cart")` passes values between the tabs of a site
+  over a `BroadcastChannel`: `cart <- e` sends and waits for nobody, `for e in cart` receives what
+  the other tabs send. `Channel` and `Topic` have what channels and topics compile to, by name, and
+  their closed zero values, `Channel.EMPTY` and `Topic.EMPTY`.
+- **Go syntax.** `func`, the type after the name, several results, errors as a second value
+  (`try JSON.parse(text)` makes what JS throws one), `defer`, a single `for` loop:
 
   ```go
   func divide(a, b number) (number, error) {
@@ -43,13 +50,16 @@ for let i = 0; i < 4; i++ {
   }
   ```
 
-- **Static types with null safety.** A `?User` cannot be used without a check.
+- **Static types with null safety.** A `?User` cannot be used without a check, and
+  `decode<User>(body)` checks JSON from outside against the type when the program runs.
 - **JavaScript inside.** The same values, classes and modules, any JS library; markup creates real
   DOM elements, and components are compiled away.
 
 The guide with examples and a playground: <https://qwern-9876r.github.io/RookLang/>.
 Specification: [docs/spec.md](docs/spec.md), design of components:
 [docs/components.md](docs/components.md), an example: [examples/hello.rk](examples/hello.rk).
+Where Rook stands and the road to 1.0: [docs/roadmap.md](docs/roadmap.md); what changed in each
+version: [CHANGELOG.md](CHANGELOG.md).
 
 ## Installation
 
@@ -60,6 +70,7 @@ npm install rooklang
 npx rook build app.rk                # app.js next to the source
 npx rook build src --out-dir dist       # every module of a folder
 npx rook run app.rk                  # compile and run
+npx rook run --watch app.rk          # and again when a file of it changes
 ```
 
 The compiled code imports what channels, goroutines and markup need from `rooklang/runtime`, so
@@ -97,9 +108,11 @@ staged version is formatted, so edits that are not staged stay out of the commit
 | `npm run vscode:package`          | Pack the VS Code extension into `rooklang.vsix`         |
 
 Options of `build`: `--out-dir dir` writes the `.js` files to a separate folder, `--stdout` prints
-the JS of one file, `--no-check` skips type checking. `--markup` and `--no-markup` turn markup and
+the JS of one file, `--no-check` skips type checking, `--no-source-map` writes no source maps
+(`app.js.map`, by default next to each `.js`). `--markup` and `--no-markup` turn markup and
 components on or off for all files (with `run` too); by default they are off, and a package turns
-them on in its `package.json`: `"rook": { "markup": true }`.
+them on in its `package.json`: `"rook": { "markup": true }`. `run --watch` runs the program again
+when a `.rk` file or a CSS module of it changes, after stopping it with `SIGTERM`.
 
 ## Releases
 
@@ -183,6 +196,20 @@ build, and in development they show up over the page. Markup and components are
 so `.rk` modules fit a React, Svelte or Vue app as they are; turn them on with
 `"rook": { "markup": true }` in `package.json`, or `rook({ markup: true })`.
 
+### Tests
+
+Rook has no test runner of its own: Vitest, with the same plugin in `vitest.config.ts`, runs tests
+of `.rk` modules, written in JS or TS. Goroutines work there too: a worker thread of Vitest loads
+the `.rk` modules with the loader of `rook run`.
+
+```ts
+// math.test.ts
+import { expect, it } from 'vitest';
+import { add } from './math.rk';
+
+it('adds', () => expect(add(1, 2)).toBe(3));
+```
+
 ## Conventions
 
 - Imports are written with the `.ts` extension (`import { x } from './lexer.ts'`).

package/README.ru.md

@@ -25,14 +25,21 @@ close(jobs)
 for let i = 0; i < 4; i++ {
     console.log(<-results)
 }
+close(results)
 ```
 
 - **Горутины и каналы.** `go f(x)` запускает функцию горутиной, на другом процессоре, а каналы,
-  `select`, `after`, `tick` и `cancel` работают как в Go; `go for i, v in pixels { ... }` делит
+  `select`, `after`, `tick` и `cancel` работают как в Go, а сигналы и `AbortSignal` тоже становятся
+  каналами, `signal("SIGTERM")` и `done(request.signal)`; `go for i, v in pixels { ... }` делит
   массив между процессорами. Компилятор проверяет, что уходящее в другой поток можно туда
-  скопировать.
-- **Синтаксис Go.** `func`, тип после имени, несколько результатов, ошибки вторым значением,
-  `defer`, один цикл `for`:
+  скопировать, и предупреждает о канале, который никогда не закрывают; экземпляр `data class`
+  уходит вместе с классом и методами.
+- **Топики между вкладками.** `topic<CartEvent>("cart")` передаёт значения между вкладками сайта
+  поверх `BroadcastChannel`: `cart <- e` отправляет и никого не ждёт, `for e in cart` принимает то,
+  что шлют другие вкладки. В `Channel` и `Topic` лежит то, во что компилируются каналы и топики, по
+  именам, и их закрытые нулевые значения `Channel.EMPTY` и `Topic.EMPTY`.
+- **Синтаксис Go.** `func`, тип после имени, несколько результатов, ошибки вторым значением
+  (`try JSON.parse(text)` делает им то, что бросил JS), `defer`, один цикл `for`:
 
   ```go
   func divide(a, b number) (number, error) {
@@ -43,13 +50,16 @@ for let i = 0; i < 4; i++ {
   }
   ```
 
-- **Статическая типизация с null-safety.** Значение типа `?User` нельзя использовать без проверки.
+- **Статическая типизация с null-safety.** Значение типа `?User` нельзя использовать без проверки,
+  а `decode<User>(body)` во время работы сверяет с типом JSON, пришедший извне.
 - **Внутри — JavaScript.** Те же значения, классы и модули, любые JS-библиотеки; разметка создаёт
   настоящие DOM-элементы, а компоненты исчезают при компиляции.
 
 Руководство с примерами и песочницей: <https://qwern-9876r.github.io/RookLang/ru/>.
 Спецификация: [docs/spec.ru.md](docs/spec.ru.md), концепция компонентов:
 [docs/components.ru.md](docs/components.ru.md), пример: [examples/hello.rk](examples/hello.rk).
+Где Rook сейчас и путь к 1.0: [docs/roadmap.ru.md](docs/roadmap.ru.md); что изменилось в каждой
+версии: [CHANGELOG.ru.md](CHANGELOG.ru.md).
 
 ## Установка
 
@@ -60,6 +70,7 @@ npm install rooklang
 npx rook build app.rk                # app.js рядом с исходником
 npx rook build src --out-dir dist       # все модули папки
 npx rook run app.rk                  # скомпилировать и запустить
+npx rook run --watch app.rk          # и запускать снова, когда меняется его файл
 ```
 
 Скомпилированный код импортирует то, что нужно каналам, горутинам и разметке, из
@@ -98,9 +109,11 @@ Node.js ≥ 24 (`nvm use`). Компилятор написан на TypeScript,
 | `npm run vscode:package`          | Упаковать расширение для VS Code в `rooklang.vsix`       |
 
 Опции `build`: `--out-dir dir` — писать `.js` в отдельную папку, `--stdout` — вывести JS одного
-файла в консоль, `--no-check` — без проверки типов. `--markup` и `--no-markup` включают или
+файла в консоль, `--no-check` — без проверки типов, `--no-source-map` — без source maps
+(`app.js.map`, по умолчанию рядом с каждым `.js`). `--markup` и `--no-markup` включают или
 выключают разметку и компоненты для всех файлов (и в `run`); по умолчанию они выключены, а пакет
-включает их в своём `package.json`: `"rook": { "markup": true }`.
+включает их в своём `package.json`: `"rook": { "markup": true }`. `run --watch` запускает программу
+заново, когда меняется её `.rk`-файл или CSS-модуль, сначала остановив её через `SIGTERM`.
 
 ## Релизы
 
@@ -183,6 +196,20 @@ export default defineConfig({ plugins: [rook()] });
 есть; включить их можно через `"rook": { "markup": true }` в `package.json` или
 `rook({ markup: true })`.
 
+### Тесты
+
+Своего запускателя тестов у Rook нет: Vitest с тем же плагином в `vitest.config.ts` запускает тесты
+`.rk`-модулей, написанные на JS или TS. Горутины там тоже работают: поток воркера Vitest загружает
+`.rk`-модули загрузчиком `rook run`.
+
+```ts
+// math.test.ts
+import { expect, it } from 'vitest';
+import { add } from './math.rk';
+
+it('adds', () => expect(add(1, 2)).toBe(3));
+```
+
 ## Соглашения
 
 - Импорты пишутся с расширением `.ts` (`import { x } from './lexer.ts'`).

package/dist/ast/declarations.d.ts

@@ -1,4 +1,4 @@
-import type { Expression, Identifier, StringLiteral } from './expressions.ts';
+import type { Expression, FuncExpression, Identifier, StringLiteral } from './expressions.ts';
 import type { TypeMember, TypeNode, TypeReference } from './markup.ts';
 import type { BlockStatement, Statement } from './statements.ts';
 export interface NodeBase {
@@ -57,6 +57,19 @@ export interface Parameter extends NodeBase {
      * properties, which `{...attrs}` puts on one of its elements.
      */
     rest?: true;
+    /**
+     * `bind active string`: a property of a component that it may change. `bind:active={tab}`
+     * writes the changes into the parent's `tab`; without it the property is the component's state.
+     */
+    bind?: true;
+    /**
+     * `constructor(private name string)`: the parameter is a property too, which the constructor
+     * assigns, as in TypeScript.
+     */
+    property?: {
+        visibility: Visibility;
+        readonly?: true;
+    };
 }
 /**
  * `comp Card(title string, children Content) { ...; return <section>...</section> }`. Components
@@ -89,6 +102,11 @@ export interface DecoratorDeclaration extends NodeBase {
     params: Parameter[];
     /** `needs cart, auth`: the decorators whose public members it uses; they are applied above it. */
     needs: Identifier[];
+    /**
+     * `includes visible(margin), cart`: decorators applied with it, above its own body, whose
+     * arguments see its parameters. Their public members are its own for the component, `@shop.count`.
+     */
+    includes: DecoratorUse[];
     body: BlockStatement;
 }
 /** `@visible("300px")` or `@visible` before `comp`; the arguments are positional. */
@@ -110,19 +128,29 @@ export interface VariableDeclaration extends NodeBase {
     exported: boolean;
     keyword: 'let' | 'const' | 'state' | 'derived' | 'ref';
     /**
-     * `public state`, `public derived` or `public const` in a decorator: the component reads it with
-     * `get(@name.x)`.
+     * `public state`, `public derived` or `public const` in a decorator: the component reads it as
+     * `@name.x`.
      */
     isPublic: boolean;
     /** `_` is an ordinary identifier here; the checker treats it as "skip this value". */
     names: Identifier[];
     type: TypeNode | null;
     values: Expression[];
+    /**
+     * `derived summary string { ...; return text }`: the block that computes a derived value, a
+     * function without parameters, so that what looks for the `return`s, `defer`s and `break`s of a
+     * component stops at it, as at other functions. Its result type is `type`; `values` is empty.
+     */
+    body: FuncExpression | null;
 }
 /** `class Admin extends User implements Shape { ... }` */
 export interface ClassDeclaration extends NodeBase {
     kind: 'ClassDeclaration';
     exported: boolean;
+    /** `data class Point`: its fields are data, and its instances go to goroutines with the class. */
+    data: boolean;
+    /** `abstract class Shape`: it has no instances of its own, only those of its subclasses. */
+    abstract?: true;
     name: Identifier;
     typeParams: TypeParameter[];
     /** An expression, as in JS, so that classes from JS modules can be extended. */
@@ -138,6 +166,8 @@ export interface FieldDeclaration extends NodeBase {
     /** `public` when no modifier is written. */
     visibility: Visibility;
     isStatic: boolean;
+    /** `readonly id string`: assigned only by its value or in the constructor of its class. */
+    readonly?: true;
     name: Identifier;
     type: TypeNode | null;
     value: Expression | null;
@@ -156,10 +186,15 @@ export interface MethodDeclaration extends NodeBase {
     isStatic: boolean;
     /** `async load() User`, like `async func`. */
     async?: true;
+    /** `get area() number { ... }` and `set area(v number) { ... }`, as in JS. */
+    accessor?: 'get' | 'set';
+    /** `abstract area() number`: no body, each subclass that is not abstract implements it. */
+    abstract?: true;
     name: Identifier;
     params: Parameter[];
     results: TypeNode[];
-    body: BlockStatement;
+    /** `null` for an abstract method. */
+    body: BlockStatement | null;
 }
 /** `interface Shape { name string; area() number }` */
 export interface InterfaceDeclaration extends NodeBase {

package/dist/ast/expressions.d.ts

@@ -1,7 +1,7 @@
 import type { NodeBase, Parameter } from './declarations.ts';
 import type { ElementExpression, TypeNode } from './markup.ts';
 import type { BlockStatement } from './statements.ts';
-export type Expression = Identifier | NumberLiteral | BigIntLiteral | StringLiteral | TemplateLiteral | BooleanLiteral | NullLiteral | ThisExpression | SuperExpression | ArrayLiteral | ObjectLiteral | FuncExpression | ArrowFunction | UnaryExpression | BinaryExpression | ConditionalExpression | CallExpression | NewExpression | MemberExpression | IndexExpression | ElementExpression | DecoratorMember | DecoratorGet | AsExpression | GoExpression | ChanExpression | StreamChanExpression | QueueExpression | ConversionExpression | MakeExpression;
+export type Expression = Identifier | NumberLiteral | BigIntLiteral | StringLiteral | RegExpLiteral | TemplateLiteral | BooleanLiteral | NullLiteral | ThisExpression | SuperExpression | ArrayLiteral | ObjectLiteral | FuncExpression | ArrowFunction | UnaryExpression | BinaryExpression | ConditionalExpression | CallExpression | NewExpression | MemberExpression | IndexExpression | ElementExpression | DecoratorMember | AsExpression | GoExpression | ChanExpression | StreamChanExpression | QueueExpression | TopicExpression | DecodeExpression | TryExpression | ConversionExpression | MakeExpression;
 /**
  * `[]byte("rook")`: the UTF-8 bytes of a string. `string(data)`, the way back, is a call, since
  * `string` may be the name of a value.
@@ -33,6 +33,29 @@ export interface QueueExpression extends NodeBase {
     element: TypeNode;
     items: Expression | null;
 }
+/** `topic<CartEvent>("cart")`: values of the tabs of a site, over a BroadcastChannel of that name. */
+export interface TopicExpression extends NodeBase {
+    kind: 'TopicExpression';
+    element: TypeNode;
+    name: Expression;
+}
+/**
+ * `decode<User>(body)`: JSON text, or a value from JS, checked against a type when the program
+ * runs; it gives `(User, error)`.
+ */
+export interface DecodeExpression extends NodeBase {
+    kind: 'DecodeExpression';
+    type: TypeNode;
+    argument: Expression;
+}
+/**
+ * `try JSON.parse(text)`: an exception in the expression, or a rejected Promise that an `await` in
+ * it waits for, becomes the error of `(T, error)`.
+ */
+export interface TryExpression extends NodeBase {
+    kind: 'TryExpression';
+    argument: Expression;
+}
 /**
  * `chan(res.body, 4)`: a channel that receives the chunks of a ReadableStream, with room for 4,
  * and a channel that gets the error of the stream, or null at its end.
@@ -82,6 +105,13 @@ export interface StringLiteral extends NodeBase {
     /** Source text including quotes. */
     raw: string;
 }
+/** `/ab+c/gi`, which JS writes the same way. */
+export interface RegExpLiteral extends NodeBase {
+    kind: 'RegExpLiteral';
+    /** As it is written, between the slashes. */
+    pattern: string;
+    flags: string;
+}
 /** `` `Hello, ${name}!` ``: `quasis` always has one element more than `expressions`. */
 export interface TemplateLiteral extends NodeBase {
     kind: 'TemplateLiteral';
@@ -201,16 +231,12 @@ export interface IndexExpression extends NodeBase {
     optional: boolean;
 }
 /**
- * `@visible.shown`: a public member of a decorator applied to the component. The names belong to
- * the decorator, not to any scope, so walkers do not visit them as identifiers.
+ * `@visible.shown` or `@visible.show()`: a public member of a decorator applied to the component,
+ * read or called. The names belong to the decorator, not to any scope, so walkers do not visit them
+ * as identifiers.
  */
 export interface DecoratorMember extends NodeBase {
     kind: 'DecoratorMember';
     decorator: Identifier;
     member: Identifier;
 }
-/** `get(@visible.shown)`: reads public state or a constant of a decorator. */
-export interface DecoratorGet extends NodeBase {
-    kind: 'DecoratorGet';
-    target: DecoratorMember;
-}

package/dist/ast/markup.d.ts

@@ -60,7 +60,7 @@ export interface EventHandler extends NodeBase {
     kind: 'EventHandler';
     body: SimpleStatement[];
 }
-export type TypeNode = TypeReference | ArrayType | NullableType | FuncType | ComponentType | ObjectType | UnionType | LiteralType | ChanType | QueueType;
+export type TypeNode = TypeReference | ArrayType | NullableType | FuncType | ComponentType | ObjectType | UnionType | LiteralType | ChanType | QueueType | TopicType;
 /**
  * `chan number`: a channel of numbers, made by `chan<number>(size)`; `chan<- number` only sends
  * and `<-chan number` only receives.
@@ -75,6 +75,11 @@ export interface QueueType extends NodeBase {
     kind: 'QueueType';
     element: TypeNode;
 }
+/** `topic CartEvent`: values that go to the other tabs of a site, made by `topic<T>(name)`. */
+export interface TopicType extends NodeBase {
+    kind: 'TopicType';
+    element: TypeNode;
+}
 /** A named type: `number`, `User`, `Point`, `Box<number>`. */
 export interface TypeReference extends NodeBase {
     kind: 'TypeReference';

package/dist/ast/statements.d.ts

@@ -4,11 +4,20 @@ import type { JsxElementStatement } from './markup.ts';
 export type Statement = ImportDeclaration | FuncDeclaration | ComponentDeclaration | DecoratorDeclaration | VariableDeclaration | ClassDeclaration | InterfaceDeclaration | TypeAliasDeclaration | BlockStatement | ExpressionStatement | AssignmentStatement | IncDecStatement | ReturnStatement | IfStatement | ForStatement | ForInStatement | SwitchStatement | BreakStatement | ContinueStatement | ThrowStatement | TryStatement | DeferStatement | MountStatement | EffectStatement | StyleStatement | DeleteStatement | JsxElementStatement | SendStatement | SelectStatement;
 /** Statements allowed in the `init` and `update` parts of a `for` header. */
 export type SimpleStatement = VariableDeclaration | ExpressionStatement | AssignmentStatement | IncDecStatement | DeleteStatement | SendStatement;
-/** `ch <- value`: waits until the channel takes the value, so only in async functions. */
+/**
+ * `ch <- value`: waits until the channel takes the value, so only in async functions. A send to a
+ * topic waits for nobody, so the parser, which does not know the type, leaves the error to the
+ * checker: `cannotWait` is the `<-` of a send where waiting is not allowed, and why.
+ */
 export interface SendStatement extends NodeBase {
     kind: 'SendStatement';
     channel: Expression;
     value: Expression;
+    cannotWait?: {
+        inDefer: boolean;
+        start: number;
+        end: number;
+    };
 }
 export interface BlockStatement extends NodeBase {
     kind: 'BlockStatement';
@@ -44,6 +53,8 @@ export interface ReturnStatement extends NodeBase {
 }
 export interface IfStatement extends NodeBase {
     kind: 'IfStatement';
+    /** `if const v, err = f(); err != null { }`: its variables are seen in every branch, as in Go. */
+    init: VariableDeclaration | null;
     condition: Expression;
     consequent: BlockStatement;
     /** `else { ... }` or `else if ...`. */
@@ -58,6 +69,8 @@ export interface IfStatement extends NodeBase {
  */
 export interface ForStatement extends NodeBase {
     kind: 'ForStatement';
+    /** `outer: for { ... }`, for `break outer` and `continue outer` in a nested loop. */
+    label?: Identifier;
     init: SimpleStatement | null;
     condition: Expression | null;
     update: SimpleStatement | null;
@@ -69,15 +82,21 @@ export interface ForStatement extends NodeBase {
  */
 export interface ForInStatement extends NodeBase {
     kind: 'ForInStatement';
+    label?: Identifier;
     key: Identifier | null;
     value: Identifier;
     iterable: Expression;
+    /** `with key todo.id` of a `{for}` in markup: what its blocks are found again by. */
+    withKey?: Expression;
     body: BlockStatement;
     go?: boolean;
 }
 /** `switch cmd { ... }`, or `switch { ... }` without a discriminant as an if/else chain. */
 export interface SwitchStatement extends NodeBase {
     kind: 'SwitchStatement';
+    label?: Identifier;
+    /** `switch const kind = node.kind; kind { }`, as the initializer of `if`. */
+    init: VariableDeclaration | null;
     discriminant: Expression | null;
     cases: SwitchCase[];
 }
@@ -94,6 +113,7 @@ export interface SwitchCase extends NodeBase {
  */
 export interface SelectStatement extends NodeBase {
     kind: 'SelectStatement';
+    label?: Identifier;
     cases: SelectCase[];
 }
 /** A case of `select`: a receive, `<-ch`, a send, `ch <- v`, or `default` when it is null. */
@@ -104,12 +124,18 @@ export interface SelectCase extends NodeBase {
     operation: UnaryExpression | SendStatement | null;
     body: Statement[];
 }
+/** `break`, or `break outer`: the label of an enclosing loop, switch or select. */
 export interface BreakStatement extends NodeBase {
     kind: 'BreakStatement';
+    label?: Identifier;
 }
+/** `continue`, or `continue outer`: the label of an enclosing loop. */
 export interface ContinueStatement extends NodeBase {
     kind: 'ContinueStatement';
+    label?: Identifier;
 }
+/** The statements that can have a label. */
+export type LabeledStatement = ForStatement | ForInStatement | SwitchStatement | SelectStatement;
 export interface ThrowStatement extends NodeBase {
     kind: 'ThrowStatement';
     argument: Expression;
@@ -132,7 +158,7 @@ export interface DeferStatement extends NodeBase {
     body: CallExpression | BlockStatement;
 }
 /**
- * `mount() { ... }` at the top level of a component: runs once the component's markup is in the
+ * `mount { ... }` at the top level of a component: runs once the component's markup is in the
  * document. It may return a function, which runs when `{if}`, `{switch}` or `{for}` removes the
  * markup.
  */

package/dist/auto-import.d.ts

@@ -0,0 +1,11 @@
+import type { Completion, TextEdit } from './checker/checker.ts';
+import type { CompletionList } from './completion.ts';
+/** A fix of a diagnostic: the import of the name from one module. */
+export interface ImportFix {
+    title: string;
+    edit: TextEdit;
+}
+/** The names of other modules that fit where the cursor is and that are not in scope there. */
+export declare function importCompletions(source: string, filename: string, list: CompletionList): Completion[];
+/** For an error about a name that is not defined, the imports of the modules that export it. */
+export declare function importFixes(source: string, filename: string, message: string): ImportFix[];

package/dist/auto-import.js

@@ -0,0 +1,81 @@
+import { dirname, relative, resolve, sep } from 'node:path';
+import { markupFor } from "./config.js";
+import { parse } from "./parser/parser.js";
+import { projectExports } from "./project-modules.js";
+const SPACES = {
+    value: 'value',
+    type: 'type',
+    tag: 'tag',
+};
+/** The names of other modules that fit where the cursor is and that are not in scope there. */
+export function importCompletions(source, filename, list) {
+    const space = list.context && SPACES[list.context];
+    if (!space)
+        return [];
+    const known = new Set(list.items.map((item) => item.name));
+    const candidates = projectExports(filename).filter((each) => each.spaces.includes(space) && !known.has(each.name));
+    if (candidates.length === 0)
+        return [];
+    const imports = importsOf(source, filename);
+    return candidates.map((each) => {
+        const specifier = specifierOf(filename, each.path);
+        return {
+            name: each.name,
+            kind: each.kind,
+            import: { specifier, edit: importEdit(source, imports, each.name, specifier, each.path) },
+        };
+    });
+}
+const UNDEFINED = [
+    [/^"(.+)" is not defined$/, 'value'],
+    [/^unknown type "(.+)"$/, 'type'],
+    [/^unknown component <(.+)>$/, 'tag'],
+    [/^unknown decorator @(.+)$/, 'decorator'],
+];
+/** For an error about a name that is not defined, the imports of the modules that export it. */
+export function importFixes(source, filename, message) {
+    for (const [pattern, space] of UNDEFINED) {
+        const name = pattern.exec(message)?.[1];
+        if (name === undefined)
+            continue;
+        const imports = importsOf(source, filename);
+        return projectExports(filename)
+            .filter((each) => each.name === name && each.spaces.includes(space))
+            .map((each) => {
+            const specifier = specifierOf(filename, each.path);
+            return {
+                title: `Add import { ${name} } from "${specifier}"`,
+                edit: importEdit(source, imports, name, specifier, each.path),
+            };
+        });
+    }
+    return [];
+}
+/** The imports of the module, with the absolute paths of the modules they import. */
+function importsOf(source, filename) {
+    const { program } = parse(source, { markup: markupFor(filename) });
+    return program.body.flatMap((statement) => statement.kind === 'ImportDeclaration'
+        ? [[statement, resolve(dirname(filename), statement.source.value)]]
+        : []);
+}
+/** The path of a module as an import of the file `filename` writes it: "./card.rk". */
+function specifierOf(filename, path) {
+    const specifier = relative(dirname(resolve(filename)), path)
+        .split(sep)
+        .join('/');
+    return specifier.startsWith('../') ? specifier : `./${specifier}`;
+}
+function importEdit(source, imports, name, specifier, path) {
+    const same = imports.find(([node, from]) => from === path && node.namedImports.length > 0);
+    const last = same?.[0].namedImports.at(-1);
+    if (last)
+        return { start: last.end, end: last.end, text: `, ${name}` };
+    const line = `import { ${name} } from "${specifier}"`;
+    const after = imports.at(-1)?.[0];
+    if (!after)
+        return { start: 0, end: 0, text: `${line}\n\n` };
+    const end = source.indexOf('\n', after.end);
+    return end === -1
+        ? { start: source.length, end: source.length, text: `\n${line}` }
+        : { start: end + 1, end: end + 1, text: `${line}\n` };
+}

package/dist/breaks.d.ts

@@ -0,0 +1,6 @@
+import type * as ast from './ast.ts';
+/**
+ * Whether a `break` in these statements leaves the enclosing loop or switch: an unlabeled one
+ * outside of nested loops and switches, or `break label` anywhere when `label` is the statement's.
+ */
+export declare function containsBreak(statements: readonly ast.Statement[], label?: ast.Identifier | null): boolean;

package/dist/breaks.js

@@ -0,0 +1,36 @@
+import { forEachChild } from "./walk.js";
+/**
+ * Whether a `break` in these statements leaves the enclosing loop or switch: an unlabeled one
+ * outside of nested loops and switches, or `break label` anywhere when `label` is the statement's.
+ */
+export function containsBreak(statements, label = null) {
+    let found = false;
+    const visit = (node, nested) => {
+        switch (node.kind) {
+            case 'BreakStatement':
+                if (node.label ? node.label.name === label?.name : !nested)
+                    found = true;
+                return;
+            // An unlabeled `break` inside these belongs to them.
+            case 'ForStatement':
+            case 'ForInStatement':
+            case 'SwitchStatement':
+            case 'SelectStatement':
+                if (label !== null)
+                    forEachChild(node, (child) => visit(child, true));
+                return;
+            case 'FuncDeclaration':
+            case 'FuncExpression':
+            case 'ArrowFunction':
+            case 'ClassDeclaration':
+            case 'MountStatement':
+            case 'EffectStatement':
+                return;
+            default:
+                forEachChild(node, (child) => visit(child, nested));
+        }
+    };
+    for (const statement of statements)
+        visit(statement, false);
+    return found;
+}

package/dist/build.d.ts

@@ -9,6 +9,8 @@ export interface BuildOptions {
     declarations?: boolean;
     /** Markup and components for every file; by default as its package.json says (config.ts). */
     markup?: boolean;
+    /** Write a source map next to each `.js`, `app.js.map`. Defaults to `true`. */
+    sourceMap?: boolean;
 }
 export interface BuildOutput {
     /** Absolute path of the `.rk` file. */
@@ -26,6 +28,11 @@ export interface BuildOutput {
         output: string;
         code: string;
     };
+    /** The source maps of the module and of its worker module, `.js.map`, unless turned off. */
+    maps?: {
+        output: string;
+        code: string;
+    }[];
 }
 /** The errors or the warnings of a file. */
 export interface BuildError {