Documentation
¶
Overview ¶
Package plugin implements the esbuild onLoad plugin for *.pzl files (constellation/doc/DOC-COMPILER-DESIGN.md §b). Everything happens in memory, per file: read → SplitSections → codegen.Compile → return JS. Parse/codegen errors become esbuild api.Message values with file/line/col (§e) so the build fails with normal esbuild formatting; a file that fails to compile emits no output.
<style> blocks are collected into a per-plugin, mutex-guarded map (esbuild runs onLoad concurrently across files) and joined deterministically — sorted by file path — into a single global CSS string via CSS().
Index ¶
Constants ¶
const ManifestSpecifier = "@magic-spells/puzzle/formatters/manifest"
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Features ¶ added in v0.3.0
type Features struct {
Flip bool
}
Features are the build-wide DCE bits — one boolean per gated runtime module — handed to esbuild as literal defines. Kept as a comparable struct so WatchBuilder can decide with one == whether the Define set frozen into its esbuild context went stale.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin owns the cross-file state of one build: the app root (used to derive stable, app-relative filenames for error reporting and the D20 emission-mode decision) and the thread-safe <style> collector.
func New ¶
New creates a Plugin rooted at the app directory (the directory containing app/app.js). appRoot should be absolute. The root is symlink-resolved up front so relName() compares like with like: esbuild reports args.Path with symlinks resolved, and an unresolved root (macOS /var → /private/var, a symlinked project dir) would make filepath.Rel fall back to the absolute path — hashing a machine-specific string into ScopeID (D59 byte-stability).
func (*Plugin) CSS ¶
CSS returns every collected <style> block, sorted by source file path and joined with blank lines. v1 emits global CSS with no scoping.
func (*Plugin) Features ¶ added in v0.3.0
Features returns the DCE define bits captured by the most recent SetUsage call.
func (*Plugin) PruneCSS ¶
PruneCSS drops collected <style> entries whose source .pzl is not in keep, the set of absolute source paths in the current module graph (derived from the esbuild metafile after a successful incremental rebuild). This catches the one case CSS()'s os.Stat prune cannot: a file still on disk but no longer imported, whose onLoad never re-runs so its stale block would otherwise linger.
Both sides are symlink-resolved before comparison so a keep-set path computed from a cwd-relative metafile key matches a css key set from esbuild's resolved args.Path even when a symlinked prefix (macOS /tmp → /private/tmp) differs.
func (*Plugin) SetFormatters ¶
SetFormatters stores the app-wide built-in formatter union used by the virtual manifest. escape is always present as the safety default.
func (*Plugin) SetRuntimeDir ¶
SetRuntimeDir points the virtual formatter manifest at client-runtime/.
type Usage ¶ added in v0.3.0
Usage is the build-wide feature set discovered by ScanUsage.
func ScanUsage ¶ added in v0.3.0
ScanUsage walks scanRoot for first-party source usage that controls runtime tree-shaking: it parses .pzl templates for formatter chains and flip attributes. Both are template facts, so only .pzl files are read.
The scan deliberately errs toward OVER-inclusion: it walks the whole project (not just app/) so a component imported from a sibling directory still contributes its usage, and it SKIPS files it cannot read or parse rather than failing. Rationale: a false positive only leaves a small runtime module in the bundle, whereas a false negative silently removes a used feature. Since v1.12 (D43) an unseeded builtin no longer crashes the render — codegen wraps every call in the __missing typo-guard, so the value passes through with a console.error — but the scan still seeds every USED builtin so the guard stays a *typo* guard, not a bundling crutch: correctly-spelled builtins must resolve to the real formatter, not the pass-through. A genuinely broken .pzl that the app actually imports is still reported — with position info — by the esbuild .pzl OnLoad pass; the scan must not preempt that by failing the build over a file nothing imports. See DOC-COMPILER-DESIGN §b.