Crate bynkc 

Bynk v0.3 compiler library.

Compiles .bynk commons source into TypeScript modules.

Pipeline: lex → parse → resolve → check → emit.

v0.3 introduces multi-file commons and the uses mechanism. A “project” is a directory containing one or more commons; a commons is either a single .bynk file or a directory of .bynk files that share a commons name header. See compile_project.

The single-string entrypoint compile remains for v0–v0.2 fixtures and any single-file commons that does not declare uses against another commons.

Modules

cli

The bynkc command-line interface definition.

Structs

AttributedError

v0.24 (ADR 0052): a compile error attributed — where possible — to the project-relative source file it belongs to, tagged at the collection point (the phase that produced it knows which file it was processing). None is the project-level bucket: validations spanning files (group/cycle/directory consistency) with no single owning file.

CompileError

A compile error.

CompileOptions

Options for compile_project. Construct with CompileOptions::single or CompileOptions::split, then chain .target(…) / .platform(…) / .import_ext(…) to override the bundle/default-platform/.js defaults.

Compiled

A single-file compile that also returns the non-failing warnings produced on success — what a CLI prints (v0.89, ADR 0117). compile is the warning-discarding convenience over this.

CompiledFile

One generated TypeScript file.

DiscoveredCase

One discovered test "<name>" case. location points at the case-name literal (a run failure instead points at the failing assert), giving the editor click-through to the declaration before any run.

DiscoveredSuite

v0.67: a discovered test suite — one test <target> group (unit) or test integration "<suite>" (integration). name + kind mirror exactly what the NDJSON runner emits at suite-begin (kind "unit" carries the joined target name; "integration" carries the bare suite name), so the editor reconciles discovery and run documents to the same tree items.

ProjectFailure

v0.24: a failed build with its attribution and snapshots intact — what the CLI renders rich (ariadne source context per file); the plain compile_project* wrappers flatten it to the pre-v0.24 error list.

ProjectOutput

Result of compiling a project.

ProjectPaths

v0.113 (DECISION S): the project’s source tree, read from bynk.toml’s [paths] section. Test-ness is a property of the suite declaration, not of a directory, so the layout is a flat include list of trees to compile and an exclude list of subtrees to skip — not the role-named src/tests split. Each include entry is a root walked for .bynk files; a file’s identity path is relative to the include root that contains it.

StripError

A failure to strip TypeScript to JavaScript. For input produced by the Bynk emitter this should never occur — the emitter only emits valid, strip-only TypeScript (ADR 0136) — so a StripError indicates an emitter or toolchain bug rather than user error.

TestLocation

A project-root-relative path:line:col source location, structured. Line and col are 1-indexed (the bynk_syntax::span::line_col convention).

Enums

BuildTarget

The build target. Determines how cross-context calls and per-context modules are emitted (v0.8). Bundle mode is the default — all contexts emit into one TypeScript bundle and cross-context calls are direct function invocations. Workers mode produces per-context Cloudflare Worker bundles that communicate via Service Bindings.

ImportExt

The extension emitted import specifiers use (import … from "./x.<ext>").

Platform

The deploy platform — a selection axis distinct from the --target {bundle,workers} emit mode (§6.2). It chooses which bynk-<platform>.ts binding is linked for the bynk surface. v0.17 shipped cloudflare; v0.18 adds node, making the axis observable (and giving v0.19’s platform-lock enforcement a second platform to fire against).

ProjectOptionsError

v0.24 (ADR 0052 rider) / ADR 0100: the project-failure flattening layer. #521: the implementation is shared with the bynk driver in [bynk_driver]; these re-exports keep bynkc’s public API (and its callers) unchanged. Why [try_project_options] could not produce a usable CompileOptions: either the manifest itself is unreadable (ProjectPathsError), or a well-formed manifest names a project tree that can’t be walked ([discovery::DiscoveryError]) — #1081 review.

ProjectPathsError

A problem in bynk.toml that try_read_project_paths surfaces instead of silently falling back to the conventional layout.

Roots

Where a project’s .bynk files live.

SchemaLock

bynk-emit’s CompileOptions::schema_registry value — whether a build reconciles bynk.schema.lock, and if so, its current content.

Severity

Severity classification for a CompileError. Mirrors LSP severity levels so the LSP server can map diagnostics to the protocol without reinterpreting error categories. Lives in the syntax leaf beside CompileError (it classifies one): shared by the IDE diagnose path (bynk-ide) and the short/json renderers, without either depending on the other.

Constants

NODE_MAJOR_FLOOR

Minimum supported Node.js major version for the node platform binding and for running Bynk’s emitted TypeScript.

Functions

compile

Compile a single Bynk source string to a TypeScript string.

compile_project

Compile a Bynk project, keeping error attribution + snapshots on failure (so the CLI can render project errors with source context, ADR 0052). Use .map_err(ProjectFailure::flatten) for the flattened Vec<CompileError> shape.

compile_with_warnings

The warning-preserving single-file compile behind compile. See Compiled.

print_errors

Render to stderr with color, used by the CLI.

print_errors_short

v0.38 (ADR 0071): one terse line per diagnostic for tooling consumers (bynkc check --format short): path:line:col: <severity>[<category>]: <message>. Line/column are 1-indexed, computed from the byte span against the source. The VS Code bynkc problem-matcher keys off this exact shape — keep it stable.

print_project_errors

Render project-level errors as plain [category] message lines — the fallback for errors with no file attribution. Rich, source-context rendering lives in the front-end’s project-failure renderer (v0.24).

print_project_failure

v0.24 (ADR 0052 rider) / ADR 0100: the project-failure flattening layer. #521: the implementation is shared with the bynk driver in [bynk_driver]; these re-exports keep bynkc’s public API (and its callers) unchanged. Render a project build failure with per-file ariadne context, exactly as single-file mode had rich rendering. Unattributed (project-level) errors keep the plain form.

print_project_failure_short

v0.24 (ADR 0052 rider) / ADR 0100: the project-failure flattening layer. #521: the implementation is shared with the bynk driver in [bynk_driver]; these re-exports keep bynkc’s public API (and its callers) unchanged. The project-failure analogue of bynk_render::print_errors_short: each attributed error is positioned against its file’s snapshot; an unattributed (project-level) error falls back to <severity>[<category>]: <message>.

print_project_warnings

v0.24 (ADR 0052 rider) / ADR 0100: the project-failure flattening layer. #521: the implementation is shared with the bynk driver in [bynk_driver]; these re-exports keep bynkc’s public API (and its callers) unchanged. v0.89 (ADR 0117): print a successful build’s non-failing warnings, with real per-file ariadne context now that a successful build’s snapshots (mirroring ProjectFailure::snapshots) make that possible. A warning whose source isn’t attributable (or doesn’t fit the snapshot) falls back to the plain warning[<category>]: <message> form.

project_failure_short_lines

v0.24 (ADR 0052 rider) / ADR 0100: the project-failure flattening layer. #521: the implementation is shared with the bynk driver in [bynk_driver]; these re-exports keep bynkc’s public API (and its callers) unchanged. The string form of print_project_failure_short: one path:line:col: severity[category]: message line per attributed error (an unattributed project-level error falls back to severity[category]: message). Backs both the printer above and the bynkc test --format json compile-error document, whose diagnostics the VS Code bynkc problem-matcher re-parses — each Vec entry is exactly one line by that contract, so unlike the other renderers in this file this one deliberately does not grow note/label continuation lines (finding #47): doing so would break a machine consumer that re-parses every entry as a single diagnostic line.

render_errors

Render a list of compile errors to a string (for tests) using the given filename as the diagnostic source label.

render_errors_plain

Render a list of compile errors to a string with colour disabled and the given filename as the source label. Unlike render_errors, the output contains no ANSI escape codes, so it is byte-stable — suitable for the committed diagnostic transcripts under site/src/diagnostics/.

render_errors_short

The string form of print_errors_short — one …[category]: message line per error, each newline-terminated. The renderer behind the CLI’s --format short, exposed for testing.

render_project_errors

Render a list of compile errors as plain [category] message lines (with notes and labels), for test assertion.

strip_project_to_js

Rewrite a compiled ProjectOutput from TypeScript into a JavaScript artefact (the in-browser track’s first-class JS output — ADR 0137). The emitter always produces TypeScript; a JS artefact is that same output with types stripped, which is total because the emitter is strip-only (ADR 0136).

strip_types

Strip TypeScript types from source, returning equivalent JavaScript.

try_read_project_paths

Read bynk.toml’s [paths] section, surfacing a malformed manifest — a parse failure or an unrecognised [paths] key — as an error instead of silently falling back to the conventional layout (the previous read_project_paths total form’s behaviour, R3.8 — deleted in favour of this at all 18 of its callers, #1113).

write_compiled_file

Write a single CompiledFile under dir, map-aware: a .bynk-sourced file gets a sibling .ts.map and a //# sourceMappingURL trailer (slice 1, ADR 0103); a file with no map is written verbatim. Shared by write_output and bynkc test’s output loops, so every disk-writing path emits maps uniformly (slice 2 — bynkc test --inspect runs the emitted .ts directly and needs the maps on disk). The trailer lives only on the on-disk artefact; the in-memory file.typescript stays trailer-free, so golden comparisons are unaffected. The map name appends .map to the output file name.

write_output

Write a ProjectOutput’s files under dir, creating parent directories as needed. The shared writer behind both bynkc’s compile/test paths and bynk dev’s in-process build (slice 7) — so the on-disk result is identical however the build was driven.