codegen

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 25, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package codegen turns a parsed .pzl template (constellation/doc/DOC-COMPILER-DESIGN.md §c) into the generated JS module — the user's <script> emitted VERBATIM plus an injected runtime import and an appended `Name.prototype.render = function () {…}` (constellation/doc/DOC-COMPILER-DESIGN.md §d, constellation/doc/DOC-APP-ANATOMY.md §1). The correctness anchor is the Phase 1 hand-written fixture tests/fixtures/todos/Home.compiled.js (D14): this codegen reproduces its render function mechanically.

Formatting is byte-exact against the fixture; the golden-file harness (golden_test.go) is a byte-compare. The idioms are documented inline where they are emitted.

Whitespace / text policy (derived from Home.pzl vs Home.compiled.js)

Applied to template Text nodes only (never to attribute values, which keep their bytes). For each Text node:

  • collapse every run of ASCII whitespace to a single space;
  • strip the leading space if the original leading whitespace run contained a newline (i.e. it was source indentation); strip the trailing space likewise;
  • if the result is empty, drop the node.

So "\n Made with " → "Made with " (indentation gone, the space before the next inline element kept) and pure inter-element indentation ("</h2>\n <form>") drops entirely. Consecutive Text/Interpolation siblings coalesce into ONE text vnode whose value is the `+`-concatenation of quoted literals and `String(expr)` parts.

Index

Constants

View Source
const SVGAssetSpecifierPrefix = "@magic-spells/puzzle/svg-asset/"

SVGAssetSpecifierPrefix is the import-specifier prefix for a {#svg} shared asset module: the use-site import is `<prefix><app/assets-relative src>` (e.g. "@magic-spells/puzzle/svg-asset/icons/heart.svg"). The esbuild plugin owns resolving it to the file on disk and serving the factory module (dedup mode); pzlc standalone never emits it (it inlines).

Variables

This section is empty.

Functions

func SVGAssetModule

func SVGAssetModule(data []byte, filename, viewNodeImport string) (string, error)

SVGAssetModule builds the JS source of a shared {#svg} asset module from a resolved SVG file's bytes: it scans the single <svg> root (same ScanSVGFile the inline path uses, so the vnode is identical) and emits a factory that returns a fresh island-frozen `<svg>` vnode on each call. viewNodeImport is the module specifier to import ViewNode from (the runtime's index). filename positions any malformed-file error inside the svg. The factory takes an optional `key` so a dedup use site inside a {#for} still reconciles by key.

func ScopeID

func ScopeID(filename string) string

ScopeID derives the stable per-file scope id for <style scoped> (v1.27, D59): `pzl-` + 8 lowercase hex chars of FNV-1a-32 over the compiler-relative, forward-slash-normalized source path. It is the SINGLE source of the id — both the codegen root stamp (data-<id>) and the esbuild plugin's @scope CSS wrapper call this so the attribute and the rule always agree. Path-derived, so it is byte-stable across machines (golden reproducibility) and only changes when the .pzl is renamed (the stamp and CSS move together in the same build, D59).

Types

type EmissionMode

type EmissionMode int

EmissionMode selects the render root shape (constellation/doc/DOC-DECISIONS.md D20).

const (
	// ModeView emits a real <puzzle-view> root element carrying the template's
	// attributes — for files under app/views/** and app/layouts/**.
	ModeView EmissionMode = iota
	// ModeComponent renders inline: the render() returns the template's single
	// root element with no wrapper, and attributes on <puzzle-view> are an error.
	ModeComponent
)

func ModeForPath

func ModeForPath(path string) EmissionMode

ModeForPath applies the D20 directory convention: app/views/** and app/layouts/** compile as views; everything else is a reusable component.

type Options

type Options struct {
	Filename string
	Mode     EmissionMode

	// ModulePath is the app-root-relative, forward-slashed path of the source
	// .pzl (e.g. "app/views/Home.pzl"), stamped onto the compiled class as
	// `Class.__pzlModule = "<path>"` so the static-pages build (D81) can map a
	// route's view/layout classes back to their source modules for per-page entry
	// generation. The esbuild plugin threads its app-relative `name` in here.
	// Empty means "no app root is known" (the standalone pzlc single-file path and
	// the codegen goldens): the stamp then falls back to the plain basename of
	// Filename.
	ModulePath string
	// AssetsDir is the absolute (or test-relative) path of the app's assets dir
	// ({#svg} paths resolve from here, v1.14 D46). Empty means "not configured":
	// any {#svg} then fails with a "this project has no app/assets/ directory"
	// error.
	AssetsDir string

	// SVGDedup selects the dedup emission for {#svg} (v1.14 D46 amendment): each
	// use site becomes a call to a per-asset shared factory imported from a
	// virtual module (`@magic-spells/puzzle/svg-asset/<src>`) that the esbuild
	// plugin resolves + serves, so esbuild stores each unique icon ONCE across the
	// bundle. The plugin sets this true. Left false (pzlc standalone, no bundler),
	// codegen inlines the markup at every use site as before — a self-contained
	// module with no unresolved virtual imports.
	SVGDedup bool
}

Options configure a compile.

type Result

type Result struct {
	JS           string
	InlinedFiles []string
	// Warnings are non-fatal codegen diagnostics (v0.1 hardening): a template
	// expression that references a <script> import, which resolveExpr rewrites to
	// __d.<name> → undefined at render (SPEC §6). Out-of-band — the generated JS is
	// unaffected, so goldens never move. The plugin/pzlc print them to stderr.
	Warnings []Warning
}

Result is the output of Compile: the generated module JS and the absolute (or as-joined) paths of every file inlined via {#svg} (deduped + sorted, v1.14 D46). InlinedFiles is populated even when Compile returns an error — a missing svg's attempted path is recorded so the plugin can hand it to esbuild as a WatchFile, invalidating the cached failure once the file appears.

func Compile

func Compile(sec *parser.Sections, opts Options) (*Result, error)

Compile splits are already done by the caller: it takes the Sections (scripts + template attrs) and produces the full generated module string plus the list of {#svg}-inlined files (Result). The template is parsed here so parse and codegen share one entry point. The returned *Result is always non-nil — even on error, so InlinedFiles (the {#svg} paths seen so far) is available to the caller for esbuild WatchFiles.

type Warning

type Warning struct {
	File    string
	Line    int
	Col     int
	Message string
}

Warning is a positioned, non-fatal codegen diagnostic. See Result.Warnings.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL