@chilts/weave 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -8,6 +8,130 @@ While the version is below `1.0.0`, breaking changes may land in minor releases.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-22
+
+### Added
+
+- **`unless`.** `unless cond` renders its block when `cond` is falsy,
+  compiling to the same ternary as `if !(cond)`. It is a guard only: an
+  `else` or `else if` after it is a compile error asking for an `if` with the
+  branches swapped. Previously `unless` was a compile error pointing at
+  `if !(cond)`.
+
+- **Class arrays/objects and style objects.** `class=` accepts an array
+  (nested, with `null`/`undefined`/`false`/`""` dropped) or an object whose
+  truthy keys are kept, also when merged with shorthand classes:
+  `li.item(class=({ active: isActive }))` renders `class="item active"`.
+  `style=` accepts an object: `div(style=({ marginTop: 0 }))` renders
+  `style="margin-top:0"`. Previously these rendered `class="a,b"` or
+  `[object Object]`. The `Attrs` type now types `class` and `style` with the
+  new exported `ClassValue` and `StyleValue` types, and `mergeClass()` accepts
+  any `ClassValue`.
+
+- **htmx example and docs.** A new `examples/htmx/` shows a page and the
+  fragment endpoints that reuse its mixin, and the README describes using
+  Weave for server-rendered apps.
+
+- **`for ... else`.** An `else` after a `for` renders when the collection is
+  empty.
+
+- **Mixin call-site content.** A bare `block` inside a mixin renders the
+  content indented under the call (`+card("Hi")` followed by indented lines),
+  with indented lines under `block` as its default. The mixin gains a
+  `block?: () => unknown` parameter after `attrs`; a call with content passes
+  `{}` for `attrs` when it has none. One line of content can also go on the
+  call's own line, as for an element: `+btn("save") Save` or
+  `+btn("save")(class="wide")= label`. A call can't have both inline and
+  indented content (a `ParserError`). Previously text after a mixin call was
+  dropped without a word, so the button rendered empty.
+
+- **Type errors mapped back to `.weave`.** `mapDiagnostic()` takes a
+  diagnostic reported by `tsc` against a compiled `.ts` file and uses the
+  `.ts.map` written beside it to translate it to the `.weave` file, line and
+  column; `formatDiagnostic()` prints it like a `LexerError`, with a code
+  frame. An error inside a TS expression points at the exact token: in
+  `h1= user.nmae` it lands on `nmae`, not `h1`. This covers buffered code,
+  `#{}` interpolations, attribute values, `if`/`else if` conditions, `for`
+  headers, `template`/`mixin` params, and mixin call and `extends` args,
+  including every line of a multi-line param list. An error in code weave
+  generated around them points at the start of the node.
+  `decodeMappings()`, `originalPosition()` and
+  `formatCodeFrame()` are exported too. The API takes plain
+  `{ file, line, col, message }` objects, so it does not depend on the
+  `typescript` package.
+
+- **`weave check`.** `weave check views/ lib/views/` compiles the templates,
+  type-checks the whole project against its `tsconfig.json` (or
+  `--project <path>`), and prints every error — those in a compiled view at
+  their `.weave` file, line and column with a code frame, the rest as-is —
+  followed by `Found N errors.` It exits 1 on any compile or type error, so it
+  can stand in for `tsc --noEmit` in CI. It loads the project's own
+  `typescript`, now an optional peer dependency. `--watch` is not supported
+  yet.
+
+### Changed
+
+- **Layouts declare their own `<Name>Blocks` type.** The compiler now emits
+  an exported `<Name>Blocks` interface (one optional `() => unknown` member
+  per `block`) above each template with slots, instead of splicing the name
+  into the first `import type` and requiring you to write the interface.
+  This works with no type import and with several layouts in one file.
+  **Breaking:** delete any hand-written `<Name>Blocks` interface, or `tsc`
+  reports a duplicate identifier.
+
+- `for` loops now compile to the new `each()` runtime helper instead of
+  `.map()`, so compiled templates import `each` from `@chilts/weave`.
+
+- Text with `#{}` interpolation now compiles to the new `interpolate` tagged
+  template (``h("h1", {}, interpolate`Hello ${name}`)``), so compiled
+  templates import `interpolate` from `@chilts/weave`. An interpolated `null`
+  or `undefined` now renders nothing, the same as `p= value`, where it used
+  to print `null` or `undefined`.
+
+### Fixed
+
+- `raw()` and mixin output inside `#{}` were escaped: `p Hi #{raw(html)}`
+  rendered `Hi &lt;b&gt;...` and `p By #{userLink(author, {})}` showed the
+  link's markup as text. Interpolated values now render exactly as element
+  children do, so both come out as HTML.
+- A bare `block` inside a mixin compiled to invalid TypeScript
+  (`blocks.?.()`) and content indented under a mixin call was silently
+  dropped. A bare `block` outside a mixin, or a named block inside one, is now
+  a `CodegenError`.
+- `for` over a non-array iterable (`xs.entries()`, `Set`, `Map`, a generator)
+  rendered `[object Iterator Helper]` or failed to type-check; any iterable
+  now works.
+- The `Attrs` type now accepts `null`, so `a(href=x)` with `x: string | null`
+  type-checks; the runtime already omitted `null` attributes.
+- Templates return `SafeHtml`, not a string, despite 0.4.0's note that they
+  return strings directly: only doctype-led templates ever did, by accident,
+  and 0.5.0 ended that. `SafeHtml` is now the documented contract for templates
+  and mixins alike, so nested output is never escaped twice; call `String()` on
+  it for the HTML. The README's Express example passed the result straight to
+  `res.send()`, which sends it as JSON; it now calls `String()` first.
+- A mixin that never uses `attrs` compiled to an unused `attrs` parameter,
+  failing `tsc` under `noUnusedParameters`; it is now named `_attrs`. The
+  parameter stays, so call sites may still pass extra attributes.
+- A template with a single root element indented that element's children one
+  level too deep in the compiled `.ts`. Cosmetic only; the output is unchanged.
+- Pug syntax that Weave doesn't support no longer mis-parses silently; each
+  form is now a `LexerError` that names the Weave alternative. `p!= x` used to
+  drop `x`; block expansion (`li: a Home`) and anything else run onto an
+  element (`a(href="/")Home`, `br/`) dropped the rest of the line; `p.` emitted
+  `class=""` and turned its text into elements; `- const x = 1` became a `-`
+  element; and `case`, `when`, `default`, `each`, `while`, `unless`, `append`
+  and `prepend` became elements of those names. Tag interpolation
+  (`p Hello #[strong world]`) and unescaped interpolation (`p Hi !{html}`)
+  rendered their markup characters as text; `!{html}` now points at
+  `#{raw(html)}`. Empty `.` / `#` shorthands and tag names that don't start
+  with a letter are rejected too.
+- `block` took the rest of its line as the slot name, so Pug's
+  `block append scripts` compiled to invalid TypeScript
+  (`blocks.append scripts?.()`). A block name must now be a single identifier,
+  or it is a `LexerError`; `block append` / `block prepend` (and bare
+  `append` / `prepend`) point at adding a second, empty slot to the layout
+  (`block pageScripts` after `block scripts`) and filling that instead.
+
 ## [0.7.0] - 2026-10-20
 
 ### Added
@@ -168,7 +292,8 @@ Initial release — the Weave compiler and runtime.
 - Error messages with source code frames.
 - Source map generation.
 
-[Unreleased]: https://codeberg.org/chilts/weave/compare/v0.7.0...HEAD
+[Unreleased]: https://codeberg.org/chilts/weave/compare/v0.8.0...HEAD
+[0.8.0]: https://codeberg.org/chilts/weave/compare/v0.7.0...v0.8.0
 [0.7.0]: https://codeberg.org/chilts/weave/compare/v0.6.0...v0.7.0
 [0.6.0]: https://codeberg.org/chilts/weave/compare/v0.5.0...v0.6.0
 [0.5.0]: https://codeberg.org/chilts/weave/compare/v0.4.0...v0.5.0

package/ReadMe.md

@@ -66,9 +66,40 @@ export function simple({ title, content }: SimpleProps) {
 
 Now `tsc` catches type errors, your IDE gives you autocomplete, and calling `simple({ title: "Hello", content: "World" })` returns HTML.
 
+### Type-checking templates
+
+`tsc` reports errors against the compiled `.ts`, which you never edit.
+`weave check` compiles the templates, type-checks your whole project with your
+`tsconfig.json`, and reports each error in a view at its `.weave` line:
+
+```
+$ npx weave check views/ lib/views/
+weave: views/page.weave:3:5: Property 'nmae' does not exist on type '{ name: string; }'. TS2339
+ 3 |     h1= user.nmae
+   |     ^
+
+Found 1 error.
+```
+
+It exits 1 on any error, so it can replace `tsc --noEmit` in CI, and the
+`file:line:col:` format works with Emacs `compile`. It uses your project's
+`typescript` package (install it as a dev dependency) and the nearest
+`tsconfig.json`, or the one given with `--project <path>`. Errors point at the
+exact token inside an expression, attribute value, condition, parameter or
+argument, and at the start of the node for code Weave generated around them.
+
+To map diagnostics yourself (from another tool or build step), use
+`mapDiagnostic({ file, line, col, message })`, which translates a position in a
+compiled `.ts` file to its `.weave` source via the `.ts.map` beside it, and
+`formatDiagnostic()`, which prints the result with a code frame. Neither
+depends on the `typescript` package.
+
 ## Usage
 
-Templates are just functions that return strings, so they work with any framework:
+Templates are just functions that return HTML, so they work with any framework.
+Every template and mixin returns a `SafeHtml`, so its output isn't escaped
+again when nested in another template. Call `String()` on it to get the HTML
+string:
 
 ```typescript
 import express from 'express'
@@ -77,12 +108,56 @@ import { simple } from './lib/views/simple.js'
 const app = express()
 
 app.get('/', (req, res) => {
-    res.send(simple({ title: "Hello", content: "World" }))
+    res.send(String(simple({ title: "Hello", content: "World" })))
 })
 
 app.listen(3000)
 ```
 
+### Server-rendered apps and htmx
+
+Weave is a good fit for apps that render HTML on the server and swap pieces of
+it into the page — [htmx](https://htmx.org), Turbo, Unpoly, or plain `fetch`.
+
+- **Every template and mixin is an exported function.** Rendering a fragment
+  for a swap is just calling the mixin; there is no partial-rendering API.
+- **The page and its fragments share one definition.** The page loops over
+  `+todoItem(todo)`, and the endpoint returns `todoItem(todo)`, so the markup
+  can't drift apart.
+- **No runtime engine, zero dependencies.** The runtime is a few small helpers
+  with no Node-specific imports, so compiled views run on Node, Deno, Bun and
+  Cloudflare Workers alike.
+
+A mixin for one row:
+
+```
+mixin todoItem(todo: Todo)
+  li.todo(id=`todo-${todo.id}` ...attrs)
+    input(
+      type="checkbox"
+      checked=todo.done
+      hx-post=`/todos/${todo.id}/toggle`
+      hx-target=`#todo-${todo.id}`
+      hx-swap="outerHTML"
+    )
+    span= todo.text
+```
+
+The page uses it in a loop, and the toggle endpoint returns just that row:
+
+```typescript
+import { todoItem } from './lib/views/components/todo.js'
+
+// POST /todos/:id/toggle
+todo.done = !todo.done
+return new Response(String(todoItem(todo)), {
+    headers: { 'content-type': 'text/html; charset=utf-8' },
+})
+```
+
+See [`examples/htmx/`](examples/htmx/) for the full page, the mixin, and a
+web-standard `fetch` handler serving both.
+
 ## Syntax
 
 Weave's syntax will be familiar if you've used Pug.
@@ -143,6 +218,24 @@ div.pt-4(class=undefined)                      →  <div class="pt-4">
 div.btn(class=(active ? "active" : undefined)) →  <div class="btn"> when active is false
 ```
 
+#### Class arrays and objects, style objects
+
+`class=` also takes an array or an object, which suits conditional Tailwind classes. Arrays may nest and drop `null`, `undefined`, `false` and `""`; an object keeps each key whose value is truthy. Both merge with shorthand classes:
+
+```
+div(class=(["a", "b"]))                        →  <div class="a b">
+li.item(class=({ active: isActive }))          →  <li class="item active"> when isActive is true
+a(class=(["link", { "md:flex": wide }]))       →  <a class="link md:flex"> when wide is true
+```
+
+`style=` takes an object of properties. camelCase keys become kebab-case, `--custom` properties are kept as written, and `null`, `undefined`, `false` and `""` values are dropped:
+
+```
+div(style=({ marginTop: 0, "--gap": gap }))    →  <div style="margin-top:0;--gap:1rem">
+```
+
+An array or object that yields nothing omits the attribute entirely. Numbers are not given units, so write `"4px"` rather than `4` where CSS needs one.
+
 #### Multi-token values must be wrapped
 
 Because a space separates one attribute from the next, a bare (unquoted) value has to be a single token. Wrap anything longer in parentheses or backticks:
@@ -206,14 +299,28 @@ else
   p Welcome, visitor
 ```
 
+`unless cond` is a guard: its block renders when `cond` is falsy, the same as
+`if !(cond)`. It takes no `else` or `else if` — `unless … else` is a double
+negative, so write an `if` with the branches swapped instead:
+
+```
+unless user.verified
+  p Please confirm your email address.
+```
+
 ### Iteration
 
 ```
 for ( const post of posts )
   h2= post.title
   p= post.content
+else
+  p No posts yet.
 ```
 
+The optional `else` renders when the collection is empty. Any iterable works —
+arrays, `Set`, `Map`, generators, or `xs.entries()` — and it is consumed once.
+
 ### Mixins
 
 Mixins use positional args. An implicit `attrs` parameter captures any extra attributes passed at the call site.
@@ -233,6 +340,42 @@ Usage:
 +button("Delete", "secondary")(class="ml-4" data-confirm="true")
 ```
 
+#### Call-site content
+
+A bare `block` inside a mixin renders whatever is indented under the call,
+so one mixin can wrap different content each time. Lines indented under
+`block` are the default when the call has none, and `if block` tests for it:
+
+```
+mixin card(title: string)
+  .card(...attrs)
+    h2= title
+    block
+      p.muted Nothing to show.
+```
+
+```
++card("Profile")(class="wide")
+  p= user.name
+  p= user.email
++card("Recent activity")
+```
+
+The content is passed as a callback after `attrs`, so the call above compiles
+to `card("Profile", { class: "wide" }, () => ...)`. Named blocks (`block
+content`) are layout slots and are not allowed inside a mixin. See
+[`examples/mixin-block/`](examples/mixin-block/).
+
+One line of content can go on the call's own line instead, just as an
+element takes inline text or `= expr`:
+
+```
++btn("save") Save
++btn("save")(class="wide")= label
+```
+
+A call takes its content inline or indented, not both.
+
 ### Layouts with extends and blocks
 
 A layout defines named blocks as content slots:
@@ -250,6 +393,17 @@ template layout({ title }: LayoutProps)
         p © 2024
 ```
 
+The compiled layout takes its slots as a second `blocks` argument, typed by an
+interface the compiler generates from the `block` names — you don't write it:
+
+```ts
+export interface LayoutBlocks {
+    content?: () => unknown
+}
+
+export function layout({ title }: LayoutProps, blocks: LayoutBlocks = {}) {
+```
+
 A page extends the layout, filling in the blocks. Data is passed explicitly — nothing is implicitly inherited:
 
 ```
@@ -330,7 +484,7 @@ This renders as: `Hello <strong>user@example.com</strong>.` — with a space bet
 
 ### Inline elements
 
-Weave does not support inline element syntax (e.g. Pug's `#[strong bold]` tag interpolation). To mix elements within text, place each element on its own indented line and use `|` for spacing and text fragments.
+Weave does not support inline element syntax (e.g. Pug's `#[strong bold]` tag interpolation), and `#[` in text is a compile error. To mix elements within text, place each element on its own indented line and use `|` for spacing and text fragments. To show a literal `#[` (or `!{`), use a string expression: `p= "Use #[0] for the first item"`.
 
 ### Raw blocks
 
@@ -369,17 +523,65 @@ Standard TypeScript imports pass through to the compiled output:
 import type { BlogPost } from '../types/models.js'
 ```
 
+## Coming from Pug
+
+Most Pug templates read the same in Weave, but some Pug features are left out
+on purpose. Each one below is a compile error that names the Weave way to
+write it, rather than being silently mis-rendered.
+
+| Pug | Weave |
+|---|---|
+| `- const x = 1` (unbuffered code) | Templates hold no statements. Compute values in TypeScript before rendering, or use `tag= expr` |
+| `case` / `when` / `default` | `if` / `else if` / `else` |
+| `each x in xs`, `while` | `for ( const x of xs )`; for keys and values, `for ( const [k, v] of Object.entries(obj) )` |
+| `p!= html` | `p= raw(html)` |
+| `p Hi !{html}` | `p Hi #{raw(html)}` |
+| `a(href!=url)` | Attribute values are always escaped |
+| `p.` (block text) | `p!` for raw text, or `\|` lines for escaped text |
+| `li: a Home` (block expansion) | Put the child on its own indented line |
+| `#[strong bold]` (tag interpolation) | Put each element on its own line; see [Inline elements](#inline-elements) |
+| `foo/` (explicit self-closing) | Void elements like `br` and `img` close themselves |
+| `div&attributes(obj)` | `div(...obj)` |
+| `input(disabled)` | `input(disabled=true)`; see [Boolean attributes](#boolean-attributes) |
+| `extends ./layout` | `extends layout({ data })` calls the layout's template function and passes its data |
+
+**Filters** (`:markdown-it`, `include:markdown ./post.md`) are not supported
+and are not planned. Render the content in TypeScript and pass it in as a
+`raw()` value.
+
+**`block append` / `block prepend`** are not supported. A page replaces a
+layout's block completely. When pages need to add to what the layout already
+renders, give the layout a second, empty slot:
+
+```
+head
+  block scripts
+    script(src="/app.js")
+  block pageScripts
+```
+
+**Dynamic mixin calls** (`+#{name}()`) are not supported. Mixins are ordinary
+functions, so you can choose one at runtime with a buffered expression and
+pass `{}` for its `attrs`: `div= mixins[kind](item, {})`.
+
+**Implicit scope.** In Pug, included and extended templates can see their
+caller's variables. In Weave, data only travels explicitly: through template
+params, `extends layout({ ... })` and mixin args.
+
 ## Development
 
 ```bash
 npm run build       # compile TypeScript to dist/
-npm test            # run tests (vitest)
-npm run lint        # type-check without emitting (tsc --noEmit)
+npm test            # lint, then type-check, then run tests (vitest)
+npm run lint        # lint with ESLint
+npm run typecheck   # type-check without emitting (tsc --noEmit)
 ```
 
 ## Status
 
-Weave is in early design. The `examples/` directory contains paired `.weave` and `.ts` files that define the target syntax and expected compiler output. The compiler is under active development.
+Weave is usable today: the compiler, the `weave` CLI (with watch mode and source maps) and the runtime helpers are published on npm. It is still pre-1.0, so the syntax may change in a minor release — breaking changes are called out in [CHANGELOG.md](CHANGELOG.md).
+
+The `examples/` directory pairs each `.weave` template with its compiled `.ts`. Every example is compiled in the test suite and compared byte-for-byte against that file, so they double as a reference for what the compiler emits.
 
 ## Editor Support
 

package/dist/cli/check.d.ts

@@ -0,0 +1,14 @@
+export interface CheckOptions {
+    inputPath: string;
+    outputPath: string;
+    /** tsconfig.json to check against; defaults to the nearest one above the cwd. */
+    project?: string;
+}
+/**
+ * `weave check`: compile the templates, type-check the whole tsconfig program
+ * with the compiled views added, and print every diagnostic — those in a
+ * compiled view at its .weave location. Progress goes to stderr and
+ * diagnostics to stdout. Returns the exit code: 1 if anything failed.
+ */
+export declare function check(options: CheckOptions): number;
+//# sourceMappingURL=check.d.ts.map

package/dist/cli/check.js

@@ -0,0 +1,133 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { mapDiagnostic, formatDiagnostic } from '../diagnostics/index.js';
+import { compileFiles, discoverFiles, pruneOrphans, singleOutputFile } from './index.js';
+// tsc's "No inputs were found in config file". The compiled views are added
+// as roots, so a tsconfig whose include matches nothing is still fine.
+const NO_INPUTS = 18003;
+/**
+ * The project's own typescript, so `check` agrees with the user's `tsc`.
+ * Falls back to one weave itself can resolve. Not a dependency of weave: only
+ * `check` needs it, and only when it runs.
+ */
+function loadTypeScript() {
+    for (const base of [path.join(process.cwd(), 'noop.js'), import.meta.url]) {
+        try {
+            return createRequire(base)('typescript');
+        }
+        catch {
+            // Try the next location.
+        }
+    }
+    return undefined;
+}
+// Relative to the cwd when it is under it, so the path is short and editors
+// resolve it against the directory `weave check` ran in.
+function displayPath(file) {
+    const rel = path.relative(process.cwd(), file);
+    return rel.startsWith('..') || path.isAbsolute(rel) ? file : rel;
+}
+function readSource(file) {
+    try {
+        return readFileSync(file, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function compilePairs(inputPath, outputPath) {
+    if (inputPath.endsWith('.weave')) {
+        return [{ inputFile: inputPath, outputFile: singleOutputFile(inputPath, outputPath) }];
+    }
+    let files;
+    try {
+        files = discoverFiles(inputPath);
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return `${inputPath}: no such file or directory`;
+        }
+        return `${inputPath}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    if (files.length === 0)
+        return `no .weave files found in ${inputPath}`;
+    return files.map(relPath => ({
+        inputFile: path.join(inputPath, relPath),
+        outputFile: path.join(outputPath, relPath.replace(/\.weave$/, '.ts')),
+    }));
+}
+/**
+ * `weave check`: compile the templates, type-check the whole tsconfig program
+ * with the compiled views added, and print every diagnostic — those in a
+ * compiled view at its .weave location. Progress goes to stderr and
+ * diagnostics to stdout. Returns the exit code: 1 if anything failed.
+ */
+export function check(options) {
+    const ts = loadTypeScript();
+    if (!ts) {
+        console.error('weave: check needs the "typescript" package — npm i -D typescript');
+        return 1;
+    }
+    const project = options.project ?? ts.findConfigFile(process.cwd(), ts.sys.fileExists);
+    if (!project) {
+        console.error('weave: no tsconfig.json found; pass one with --project');
+        return 1;
+    }
+    if (!ts.sys.fileExists(project)) {
+        console.error(`weave: ${project}: no such file`);
+        return 1;
+    }
+    const pairs = compilePairs(options.inputPath, options.outputPath);
+    if (typeof pairs === 'string') {
+        console.error(`weave: ${pairs}`);
+        return 1;
+    }
+    const log = (msg) => console.error(msg);
+    const { written, failed } = compileFiles(pairs, true, log);
+    if (!options.inputPath.endsWith('.weave'))
+        pruneOrphans(options.inputPath, options.outputPath, log);
+    const config = ts.readConfigFile(project, ts.sys.readFile);
+    const parsed = config.error
+        ? undefined
+        : ts.parseJsonConfigFileContent(config.config, ts.sys, path.dirname(path.resolve(project)), { noEmit: true }, project);
+    const rootNames = new Set((parsed?.fileNames ?? []).map(f => path.resolve(f)));
+    for (const file of written)
+        rootNames.add(path.resolve(file));
+    const diagnostics = config.error
+        ? [config.error]
+        : parsed.errors.filter(d => d.code !== NO_INPUTS);
+    if (!config.error) {
+        const program = ts.createProgram([...rootNames], parsed.options);
+        diagnostics.push(...ts.getPreEmitDiagnostics(program));
+    }
+    const errorFiles = new Set(failed.map(f => path.resolve(f)));
+    let errors = failed.length;
+    for (const d of diagnostics) {
+        const isError = d.category === ts.DiagnosticCategory.Error;
+        const message = (isError ? '' : 'warning: ')
+            + ts.flattenDiagnosticMessageText(d.messageText, '\n') + ` TS${d.code}`;
+        if (!d.file || d.start === undefined) {
+            console.log(`weave: ${message}`);
+            if (isError)
+                errors++;
+            continue;
+        }
+        const { line, character } = d.file.getLineAndCharacterOfPosition(d.start);
+        const diag = { file: d.file.fileName, line: line + 1, col: character + 1, message };
+        const mapped = mapDiagnostic(diag) ?? diag;
+        const source = mapped === diag ? d.file.text : readSource(mapped.file);
+        console.log(formatDiagnostic({ ...mapped, file: displayPath(mapped.file) }, source));
+        if (isError) {
+            errors++;
+            errorFiles.add(path.resolve(mapped.file));
+        }
+    }
+    if (errors === 0)
+        return 0;
+    const noun = errors === 1 ? 'error' : 'errors';
+    const where = errorFiles.size > 1 ? ` in ${errorFiles.size} files` : '';
+    console.log(`\nFound ${errors} ${noun}${where}.`);
+    return 1;
+}
+//# sourceMappingURL=check.js.map

package/dist/cli/index.d.ts

@@ -1,4 +1,6 @@
 import type { IncludeResolver } from '../codegen/index.js';
+import { formatCodeFrame } from '../diagnostics/index.js';
+import { check } from './check.js';
 interface CompileArgs {
     mode: 'compile';
     inputPath: string;
@@ -11,19 +13,25 @@ interface WatchArgs {
     outputPath: string;
     sourcemap: boolean;
 }
+interface CheckArgs {
+    mode: 'check';
+    inputPath: string;
+    outputPath: string;
+    project?: string;
+}
 interface HelpArgs {
     mode: 'help';
 }
-type CliArgs = CompileArgs | WatchArgs | HelpArgs;
+type CliArgs = CompileArgs | WatchArgs | CheckArgs | HelpArgs;
 export declare class UsageError extends Error {
     constructor(message: string);
 }
 export declare function parseArgs(argv: string[]): CliArgs;
 export declare function usage(): string;
 export declare function discoverFiles(inputDir: string): string[];
-export declare function pruneOrphans(inputDir: string, outputDir: string): void;
+export declare function pruneOrphans(inputDir: string, outputDir: string, log?: (msg: string) => void): void;
 export declare function formatElapsed(ms: number): string;
-export declare function formatCodeFrame(source: string, line: number, col: number): string;
+export { formatCodeFrame, check };
 export declare function formatError(filePath: string, err: unknown, source?: string): string;
 /** Resolves `include` paths against the including file and reads their mixins. */
 export declare function includeResolver(inputFile: string): IncludeResolver;
@@ -42,8 +50,22 @@ export declare function includedFiles(inputFile: string, source: string): string
 export declare function findIncluders(inputDir: string, relPath: string): string[];
 export declare function compileFile(inputFile: string, outputFile: string, sourcemap?: boolean): void;
 export declare function compileDir(inputDir: string, outputDir: string, sourcemap?: boolean): boolean;
+/** Where single-file mode writes: <output> itself if it is a .ts, else a file inside it. */
+export declare function singleOutputFile(inputPath: string, outputPath: string): string;
+export interface CompilePair {
+    inputFile: string;
+    outputFile: string;
+}
+/**
+ * Compile each pair, logging one line per success and printing each error to
+ * stderr. Returns the outputs written and the inputs that failed, so a caller
+ * can decide what a failure means.
+ */
+export declare function compileFiles(pairs: CompilePair[], sourcemap: boolean, log?: (msg: string) => void): {
+    written: string[];
+    failed: string[];
+};
 export declare function watchDir(inputDir: string, outputDir: string, sourcemap?: boolean): () => void;
 export declare function reconcile(inputDir: string, outputDir: string, sourcemap: boolean, pending: Map<string, ReturnType<typeof setTimeout>>): void;
 export declare function main(argv: string[]): void;
-export {};
 //# sourceMappingURL=index.d.ts.map