Stylesheet Compilation

Relevant source files

• .claude/docs/packages.md
• .claude/docs/validation-pipeline.md

The xslt3 package is responsible for compiling XSLT 3.0 stylesheets into runtime-executable objects. This compilation process converts an XML DOM representation of an XSLT stylesheet into a structured, optimized, and schema-aware Stylesheet instance. This instance encapsulates fully compiled instructions, patterns, and module import/include resolutions suitable for transformation execution.

---

The Compiler Lifecycle

The compilation process begins with the creation of a Compiler via xslt3.NewCompiler(), which returns an instance configured to orchestrate stylesheet compilation xslt3/compiler.go30-32

Primary Entry

• The central compilation method is CompileStylesheet, which accepts a helium.Document (DOM of the XSLT stylesheet) and proceeds through multiple phases to return a compiled Stylesheet object or an error xslt3/compiler.go32

Compilation Stages

1. Initialization The compiler establishes a static context including namespace bindings, schema awareness, and other configuration defaults.

2. Import/Include Resolution The compiler recursively resolves all xsl:import and xsl:include directives to merge external stylesheets into a unified compilation context. This involves fetching external documents (via a CatalogResolver) and parsing them to build an import tree respecting precedence and scope xslt3/compiler.go100-102

3. Static Semantic Analysis Validates the stylesheet for correct versioning, attribute conformance, and detects unsupported constructs early.

4. Instruction Compilation Recursively compiles XSLT elements into Go structs implementing the Instruction interface, creating an executable representation xslt3/instruction.go17-20

5. Pattern Compilation Compiles xsl:template match patterns into specialized evaluators optimized for runtime node matching xslt3/pattern.go17-20

6. Streaming Analysis Performs static checks on instructions and templates to verify streamability according to W3C's XTSE3430 error code, reporting violations as static errors xslt3/compiler.go104

Key Entities and Their Roles

Entity	Responsibility
Compiler	Orchestrates the stylesheet compilation lifecycle, managing state, resolving imports/includes, and assembling the final Stylesheet xslt3/compiler.go30-32
Stylesheet	Immutable and reusable representation of a compiled XSLT stylesheet, including imported modules, templates, and instructions xslt3/stylesheet.go17-22
Instruction	Interface implemented by compiled XSLT elements; defines methods for execution during transformation xslt3/instruction.go17-20
PrincipalStylesheetModule	Root module aggregating all included and imported modules to maintain proper precedence xslt3/stylesheet.go22

Sources: xslt3/compiler.go30-32 xslt3/compiler.go100-102 xslt3/compiler.go104 xslt3/instruction.go17-20 xslt3/pattern.go17-20 xslt3/stylesheet.go17-22

---

Import and Include Handling

XSLT modularity is realized using two constructs: xsl:import and xsl:include. The compiler handles both by loading external stylesheets, parsing them, and integrating their compiled instructions with correct precedence.

Handling Logic

• xsl:include The included stylesheet’s content is effectively injected into the including stylesheet at the point of the include directive. Included templates share the including module’s import precedence.

• xsl:import Imported stylesheets are parsed and compiled with lower precedence than the importing one. This is critical for resolving template conflicts and applying proper cascade rules.

This resolution is recursive and mediated via:

• The CatalogResolver interface for URI resolution and stream provision of external documents helium/resolver.go17-20
• The helium.Parser to parse the fetched XML documents into DOM helium/parser.go9-12

The compiler updates its internal module graph to represent this import/include hierarchy, ensuring accurate precedence during template selection and execution xslt3/compiler.go100-102

Diagram: Stylesheet Module Resolution

Title: Stylesheet Import and Include Resolution Flow

Sources: xslt3/compiler.go100-102 helium/parser.go9-12 helium/resolver.go17-20

---

Instruction and Template Compilation

All XSLT elements during compilation are transformed into structures implementing the Instruction interface, which requires the method:

This interface underpins the executable model of the compiled stylesheet, allowing templated control flow, value computation, and output generation during transformation xslt3/instruction.go17-20

Mapping XSLT Elements to Instruction Types

XSLT Element	Go Type (Instruction)	Relevant Source File
xsl:template	Template	xslt3/template.go17-20
xsl:value-of	ValueOf	xslt3/instruction_value_of.go17-20
xsl:for-each	ForEach	xslt3/instruction_for_each.go17-20
xsl:call-template	CallTemplate	xslt3/instruction_call_template.go17-20

Sources: xslt3/instruction.go17-20 xslt3/template.go17-20 xslt3/instruction_value_of.go17-20 xslt3/instruction_for_each.go17-20 xslt3/instruction_call_template.go17-20

---

Pattern Compilation

Patterns, used primarily in xsl:template match attributes, are compiled to a specialized, optimized representation distinct from generic XPath expressions. These compiled patterns focus on a node-centric evaluation model, determining if a particular node matches the pattern rather than selecting nodes from an initial context xslt3/pattern.go17-20

The PatternCompiler invoked by the main Compiler applies this transformation, generating PatternMatcher instances for runtime use.

Sources: xslt3/pattern.go17-20

---

Schema-Awareness and xsl:import-schema

The compiler supports schema-aware features triggered via xsl:import-schema. Upon importing an XML Schema:

1. Schema Registration The XSD compiler processes the schema documents via xsd.Compiler, registering global element and type declarations into the stylesheet's static context .claude/docs/validation-pipeline.md13-18 Nested schema documents are loaded through an injectable fs.FS xsd/xsd.go19 xslt3 injects a schemaResolverFS to ensure nested includes obey the URIResolver policy .claude/docs/validation-pipeline.md19

2. Type Awareness in XPath The xpath3 compiler is extended to use this schema information for static type checking, contributing to optimizations and improved error diagnostics xpath3/compiler.go17-20

3. Pattern Support for Element-Type Tests Patterns can use tests like element(name, type) that leverage schema typing to match nodes by type rather than just QName, enabling richer and more accurate template selection.

This integration requires coordination between the xslt3.Compiler, the xsd package for schema processing, and the xpath3 compiler for expression compilation.

Sources: .claude/docs/validation-pipeline.md13-19 xpath3/compiler.go17-20 xsd/xsd.go19

---

Streaming Analysis (XTSE3430)

XSLT 3.0 provides streaming capabilities to transform very large XML sources using limited memory. To enforce stream safety, the compiler performs static streamability analysis on templates and instructions based on W3C's XTSE3430 specification xslt3/compiler.go104

Streaming Classification

• Posture Analysis: Classifies expressions with respect to their relationship to the streaming input (e.g., striding allows advancing with nodes flowing in the stream, whereas grounded requires total knowledge).

• Sweep Analysis: Determines how many passes or visits an expression performs over input nodes (stay, motionless, or consuming).

The compiler employs this analysis to reject stylesheets that violate streamability constraints. For example, accessing preceding-sibling axes or revisiting the same node multiple times disqualifies a template from being streamable.

If inconsistencies occur where templates are declared streamable but contain non-streamable constructs, the compilation fails with static errors, enforcing the correctness of streaming semantics xslt3/compiler.go104

Sources: xslt3/compiler.go104

---

Compilation Data Flow Diagram

The following diagram illustrates the flow from the input stylesheet document through compilation stages to the creation of the runtime stylesheets and instructions.

Title: Stylesheet Compilation Pipeline and Entity Mapping

Sources: xslt3/compiler.go30-32 xpath3/compiler.go17-20 xslt3/pattern.go17-20 xslt3/stylesheet.go17-22 xslt3/template.go17-20 xslt3/instruction.go17-20

---

Summary

The stylesheet compilation performed by the xslt3 package efficiently:

• Resolves and merges xsl:import and xsl:include modules respecting precedence.
• Compiles XSLT program constructs into Instruction implementations executable at runtime.
• Compiles patterns to optimized matchers for template selection.
• Supports schema-awareness by integrating with the xsd package and enhancing the XPath compiler.
• Analyzes program constructs for streamability, enforcing compliance with XSLT 3.0 streaming constraints (XTSE3430).

This comprehensive process yields a Stylesheet object ready for efficient and standards-compliant XSLT transformations.

---

References and Sources

• xslt3/compiler.go30-32
• xslt3/compiler.go100-104
• xslt3/instruction.go17-20
• xslt3/pattern.go17-20
• xslt3/stylesheet.go17-22
• xpath3/compiler.go17-20
• .claude/docs/validation-pipeline.md13-19
• helium/parser.go9-12
• helium/resolver.go17-20
• xslt3/template.go17-20
• xslt3/instruction_value_of.go17-20
• xslt3/instruction_for_each.go17-20
• xslt3/instruction_call_template.go17-20
• xsd/xsd.go19