API Reference / golem / golem.engine / DagEngine
C

DagEngine

Stable v0.4+ Thread-Safe P2
Principle 2: Dual-Coded Differentiation (Glyph + Color + Semantic Pills) Unlike Sphinx's plain monochromatic text class DagEngine, the high-contrast [C] glyph and blue color variable immediately cue the reader pre-attentively, while status pills convey production stability and concurrency guarantees without reading prose.

Orchestrates incremental Directed Acyclic Graph (DAG) compilation, persistent cache invalidation, and multi-view static site generation for Golem workspaces.

M

compile_view_async

Async Idempotent P3
Principle 3: Structural Left Rail Containment Rather than letting nested methods drift rightward with fragile margin-left indents (which break on mobile), the 3px vertical left rail encapsulates the method visually and dynamically highlights on focus or hover.
async def compile_view_async(
  self,
  view: AsciiDocView,
  context: RenderContext,
  config: P5 = None,
  cache_policy: CachePolicy = CachePolicy.ADVISORY
) -> CompilationResultP4
Principle 4: Atomic AST Token Interlinking Notice that AsciiDocView, RenderContext, EngineConfig, and CompilationResult are distinct interactive tokens. Clicking EngineConfig triggers an in-situ popover preview without forcing the user away from their reading position!

Compiles an individual AsciiDoc view within the execution graph. Handles asynchronous template hydration, image asset resolution, and incremental disk caching.

Tier 1: Essential Parameters P1
Parameter Type Description
view *required AsciiDocView The parsed AsciiDoc AST view object containing frontmatter and AST blocks.
context *required RenderContext Runtime metadata including site configuration, global navigation tree, and environment variables.
Show 2 Advanced Parameters (config, cache_policy)
config default: None Override workspace compilation settings (concurrency limits, strict diagnostics).
cache_policy default: ADVISORY CachePolicy Advisory file locking and SHA-256 DAG hash validation behavior.
Principle 1: Progressive Disclosure Over Exhaustive Flattening Rather than dumping all 4 parameters in an overwhelming flat table, the 2 mandatory parameters are emphasized upfront, while optional runtime options are folded into a clean disclosure drawer.
Returns
CompilationResult — Dataclass containing generated HTML artifact path, staleness hash, and diagnostics log.
Implementation Source (Python 3.12) [View Source Code] 
async def compile_view_async(
    self,
    view: AsciiDocView,
    context: RenderContext,
    config: Optional[EngineConfig] = None,
    cache_policy: CachePolicy = CachePolicy.ADVISORY
) -> CompilationResult:
    # In-situ implementation prevents disorienting jumps to GitHub
    active_cfg = config or self.config
    dag_node = self.dag.get_or_create(view.source_path)
    
    if cache_policy == CachePolicy.STRICT and dag_node.is_clean():
        return dag_node.cached_result
        
    html_output = await self.renderer.render_async(view, context)
    return self.commit_artifact(dag_node, html_output)
Principle 5: In-Situ Inspection Over Disorienting Navigation P5 Keep the developer anchored in their reading context. Traditional generators force external page hops or GitHub link jumps for auxiliary types and implementation code. Here, two native mechanisms eliminate context switching:
  • Type Definition Popover: Clicking the token immediately renders its full dataclass fields in a native top-layer popover without navigating away.
  • Collapsible Source Drawer: Expanding [View Source Code] above exposes the exact syntax-highlighted implementation in-place.
M

invalidate_staleness

Synchronous
def invalidate_staleness(
  self,
  file_path: Path,
  cascade: bool = True
) -> int

Evicts stale DAG cache artifacts when a source file or template changes on disk. If cascade=True, recursively invalidates all downstream dependency nodes.

Returns
int — Number of invalidated dependency nodes evicted from the cache.
Principle 7: Universal Accessibility as an Architectural Invariant P7 Accessibility is baked directly into the semantic markup rather than retrofitted via CSS:
  • Semantic Landmarks: Proper HTML5 landmark structure with <header role="banner">, <nav>, <main role="main">, and <aside>.
  • Keyboard Navigation & Shortcuts: Accessible skip link (Tab), power-user shortcuts (/ search, ? shortcuts modal, a annotations toggle, t theme, e expand drawers).
  • Contrast & Motion: WCAG 2.1 AA compliant palette and strict prefers-reduced-motion compliance.