plugin

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Jul 22, 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.

<styles> 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 walks scanRoot for .pzl files, parses templates, and returns the built-in formatter names used by interpolation formatter chains.

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 formatters, and it SKIPS files it cannot read or parse rather than failing. Rationale: a superset of formatters only bloats the bundle, whereas a missing one is seeded nowhere. 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.

Types

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 <styles> 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 <styles> 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) PruneCSS

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

PruneCSS drops collected <styles> 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/.

Jump to

Keyboard shortcuts

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