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.

Re-exports

pub use bynk_fmt as fmt;

Modules

actors

v0.45 actor contracts (the actors-foundations slice).

ast

Abstract syntax tree types for Bynk v0 (spec §9.2).

builtin_names

Centralised string literals for the language’s built-in vocabulary (refactor track item 8, v0.29.11). Built-in type/method names were compared as bare string literals scattered across the checker, emitter, and project modules; a typo was a silent never-match. One edit point per name now.

checker

Type checker and refinement validator (spec §§5–6, v0.1 §4.2, v0.2 §4.2).

cli

The bynkc command-line interface definition.

diagnostics

Central registry of diagnostic codes.

emitter

TypeScript emission (spec §7, v0.1 §6, v0.2 §6).

error

Compiler diagnostics.

expr_types

v0.30.2 (ADR 0063): the expression-type sink.

firstparty

First-party standard adapters embedded in the toolchain (v0.17 §4.2).

hints

v0.27 (ADR 0056): the inlay-hint sink.

index

v0.25: the project-wide binding index (ADR 0053).

kernel_methods

v0.30.2 (ADR 0063): the enumerable kernel-method registry.

keywords

Registry of reserved keywords.

lexer

Lexer for Bynk v0.

locals

v0.31 (ADR 0064): the local-binding sink.

parser

Hand-written recursive-descent parser for Bynk v0.

project

Multi-file project compilation (v0.3 §3.2 and §3.3, v0.4 §3.5).

requirements

v0.99 (ADR — agent capability provenance): the capability-requirement ledger.

resolver

Name resolution (spec §5.1, v0.1 §4.1, v0.2 §4.1).

span

Source position spans.

test_json

v0.59: the bynkc test --format json result model, plus the parser that folds the runner’s NDJSON event stream into it.

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

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

CompiledFile

One generated TypeScript file.

Diagnostic

One diagnostic produced from a recovery-mode compile of a single 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.

FileDiagnostics

Per-file diagnostics from a whole-project analysis. v0.24 (ADR 0052): text is the analysed snapshot — positions must convert against it, not a newer buffer (the analyse→publish window is real).

ProjectDiagnostics

v0.24: the result of diagnose_project. Every discovered file appears in files — clean files with an empty list — so a consumer can clear stale diagnostics. unattributed holds project-level diagnostics with no single owning file (group/cycle/directory validations).

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).

Roots

Where a project’s .bynk files live.

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

diagnose

Best-effort single-file compilation that always returns diagnostics.

diagnose_project

v0.24 (ADR 0052): non-bailing, overlay-aware, file-attributed project diagnostics — the LSP analysis entry point, distinct from compile_project (which bails and emits). overlay maps canonicalised absolute paths to buffer text layered over disk reads.

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): render a failed project build with full ariadne source context per file — the attribution built for the LSP, fixing the standing gap where project-mode CLI errors were bare lines while single-file mode had rich rendering. Unattributed (project-level) errors keep the plain form.

print_project_failure_short

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.89 (ADR 0117): print a successful build’s non-failing warnings. A successful build keeps no per-file snapshots, so warnings render in the plain warning[<category>]: <message> form (with the owning file, when known) rather than ariadne source context.

project_failure_short_lines

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.

read_project_paths

v0.113: read bynk.toml from project_root. Returns the conventional layout (see ProjectPaths::conventional) if the file is missing or declares no [paths] include. Honours include / exclude under [paths], each an array of path strings; anything else is ignored. A minimal hand-rolled TOML reader — we only need string and string-array values here.

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), 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.

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.