Documentation
¶
Overview ¶
Package gen turns a notebook graph.Graph into compilable Go source: a registry the engine can execute, generated into the notebook's own package so it can see unexported cells.
The generated code is deliberately dumb. It emits exactly two things:
- a registry of [engine.Node] values — one closure per cell that calls the real cell function with type-asserted inputs and packs its named results into engine.Outputs. The assertions are safe by construction because codegen knew the static types from the graph.
- flattened per-cell metadata (label, directives).
It knows nothing about widgets, renderers, purity policy, or the scheduler. Anything more would be the framework growing back inside the code generator, where it would go unnoticed. If codegen ever needs to understand presentation or reactivity, that is a design smell, not a feature.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GeneratedFile ¶
type GeneratedFile struct {
// Name is the base filename, e.g. "notebook_gen.go".
Name string
// Content is the gofmt'd source.
Content []byte
}
GeneratedFile is one synthesized Go source file: its virtual path relative to the module (where it must appear to live for the build) and its formatted content. Codegen writes nothing to disk — the caller maps these into a go build -overlay (see internal/gen/overlay.go).
func MainPackage ¶
func MainPackage(g *graph.Graph, info analyze.PackageInfo) (GeneratedFile, error)
MainPackage generates the tiny main package that imports the notebook package's registry, builds the engine runtime, and serves it — or, with --headless, runs one wave and prints results.
The generated main stays free of topology knowledge (the engine computes levels). It does, however, generate a TYPE-AWARE --set parser: codegen knows each leaf's static Go type from the graph, so `--set servers=120` parses the string into the leaf's real type (int, a named float64, etc.) rather than guessing at runtime. That is codegen doing what only it can — it has the static types — without knowing anything about presentation or reactivity.
func Registry ¶
func Registry(g *graph.Graph, info analyze.PackageInfo) (GeneratedFile, error)
Registry generates the notebook_gen.go registry file for the notebook package described by info and graph g.
Cells that cannot run this milestone are omitted from the executable registry but still reported: any cell with a Delayed (Prev[T]) parameter is a fold, which the engine does not yet support. Omitting it keeps the generated code compilable; the analyzer has already emitted an "unsupported" diagnostic.
func WASMMainPackage ¶
func WASMMainPackage(g *graph.Graph, info analyze.PackageInfo) (GeneratedFile, error)
WASMMainPackage generates the browser entry point: the SAME registry, engine, scheduler, and head as the server main, driven over the syscall/js boundary (engine/wasm) instead of an HTTP/SSE server. The only difference from MainPackage is the transport — the whole point of the WASM topology test.
It reuses the type-aware leaf coercer (setLeafValue): browser edits arrive as JS values (float64/bool/string), the same shapes the SSE /set path coerces, so downstream type assertions stay safe. Carries a //go:build js && wasm tag so it only compiles for the browser target.
type Overlay ¶
type Overlay struct {
// JSONPath is the path to pass as `go build -overlay=<JSONPath>`.
JSONPath string
// MainDir is the (virtual) package directory to name as the build target,
// e.g. "<module>/.notebook-build/main".
MainDir string
// contains filtered or unexported fields
}
Overlay is a go build -overlay configuration backed by a temp directory. The user's source tree is never touched; the generated files exist only virtually (mapped in the overlay JSON) and physically only in the temp dir.
func Build ¶
Build is the full codegen + overlay pipeline. It synthesizes the registry (in the notebook's package, so it sees unexported cells) and a tiny main package that imports it, writes both to a temp directory as backing files, and returns an Overlay describing the go build -overlay mapping plus the import path of the main package to build.
Nothing is written into the user's source tree — the whole point of the overlay. The returned Overlay owns a temp dir the caller must Cleanup.
func BuildWASM ¶
BuildWASM is Build for the browser target: it synthesizes the same registry but a syscall/js entry point (via WASMMainPackage) instead of the server main. The engine, scheduler, head, and cache are byte-identical — only the transport differs. Build with GOOS=js GOARCH=wasm against the returned Overlay.MainDir.
type PosMap ¶
type PosMap struct {
// Entries maps a 1-based line number in the generated file to a cell.
Entries map[int]graph.CellID
}
PosMap maps a line in the generated registry back to the cell it came from. It is the seam for browser-IDE diagnostics: when a future hosted editor surfaces a build error against the synthesized file, this lets it be remapped to the cell the author actually wrote.
It is unused this milestone and deliberately minimal. go build errors inside cell *bodies* already point at the user's real source (cells are ordinary functions in an ordinary package); only the machine-generated registry would ever need remapping, and it should never fail to compile. The map exists now so the capability is additive later, not a retrofit.
type Provenance ¶
type Provenance struct {
SourceHash string
Commit string
Dirty bool
BuiltAt string
GoVersion string
}
Provenance is what produced an artifact: the content identity of its source plus the git/build context. It is computed at build time and emitted into the generated registry as engine.Provenance, so a frozen binary can say what it is. A path is not a handle; the source hash is the handle.
Source Files