plugin

package
v0.3.0 Latest Latest
Warning

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

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

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

View Source
const ManifestSpecifier = "@magic-spells/puzzle/formatters/manifest"

Variables

This section is empty.

Functions

func ScanFormatters

func ScanFormatters(scanRoot string) (map[string]bool, error)

ScanFormatters preserves the original formatter-only API for focused callers and tests. Build orchestration uses ScanUsage so every tree-shaking input is refreshed together.

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

func New(appRoot string) *Plugin

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

func (p *Plugin) CSS() string

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

func (p *Plugin) ESBuild() api.Plugin

ESBuild returns the api.Plugin to register in BuildOptions.Plugins.

func (*Plugin) Features added in v0.3.0

func (p *Plugin) Features() Features

Features returns the DCE define bits captured by the most recent SetUsage call.

func (*Plugin) PruneCSS

func (p *Plugin) PruneCSS(keep map[string]bool)

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

func (p *Plugin) SetFormatters(used map[string]bool)

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

func (p *Plugin) SetRuntimeDir(dir string)

SetRuntimeDir points the virtual formatter manifest at client-runtime/.

func (*Plugin) SetUsage added in v0.3.0

func (p *Plugin) SetUsage(usage Usage)

SetUsage stores every build-wide usage bit discovered by ScanUsage. Formatter manifest behavior stays identical; the booleans feed esbuild's literal DCE defines.

type Usage added in v0.3.0

type Usage struct {
	Formatters map[string]bool
	HasFlip    bool
}

Usage is the build-wide feature set discovered by ScanUsage.

func ScanUsage added in v0.3.0

func ScanUsage(scanRoot string) (Usage, error)

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.

Jump to

Keyboard shortcuts

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