cloudflare·Mar 27, 2026·2 min readCurated summary

How we use Abstract Syntax Trees (ASTs) to turn Workflows code into visual diagrams

Cloudflare uses Abstract Syntax Trees (ASTs) to turn code-based Workflows into visual diagrams. Because Workflows execute dynamically—supporting parallel promises, awaits, loops, and conditionals—the system analyzes code structure and relationships to infer execution order. The resulting diagrams help developers understand workflow shape, especially as coding agents generate more application code. ## Why Code-Based Workflows Are Difficult to Visualize - Unlike declarative workflow builders, Cloudflare Workflows are ordinary code. - Workflows may contain: - `Promise` and `await` relationships - `Promise.all` for parallel execution - Loops and conditionals - Steps nested inside functions or classes - The runtime discovers and executes steps as it encounters them, rather than following a predefined sequence. - Unawaited steps can execute in parallel, while `await` establishes blocking dependencies. ## How Workflow Execution Works - A supervisor Durable Object, called the engine, starts for each workflow instance. - The engine dispatches execution to the user Worker. - When the Worker encounters `step.do`, control returns to the engine. - The engine executes the step, persists its result or error, and invokes the Worker again. - Since the engine does not inherently retain the complete intended order of steps, diagram generation must reconstruct those relationships from the source code. ## Parsing and Building the Workflow Graph - Cloudflare fetches the bundled Worker script at deployment time. - A parser converts the script into an Abstract Syntax Tree. - An internal service: - Identifies `WorkflowEntrypoints` - Finds calls to workflow steps - Builds and traverses an intermediate graph - Produces the final diagram through Cloudflare’s API - AST analysis tracks promises and `await` expressions to determine: - Which steps depend on one another - Which steps block execution - Which steps can run concurrently ## Handling Bundled and Minified JavaScript - Workers are generally bundled with tools such as esbuild and may be minified. - Minified output can obscure the original TypeScript structure and vary between bundlers. - The diagram system therefore has to recognize workflow patterns in dense, transformed JavaScript. - For example, several agent steps—such as summary, correctness, and clarity agents—may be created without awaiting them, indicating parallel execution. - The generated graph makes that concurrency visible even when the deployed code is difficult to read. Cloudflare’s AST-based approach provides a practical way to visualize dynamic, code-defined workflows. Developers can inspect how steps connect, branch, and execute in parallel directly from the dashboard, though the beta diagrams will continue to improve as more workflow patterns are supported.

Read original(opens in new tab)

Json ConfigurationCloudflareTypeScriptJavaScript+4

datadog·Feb 14, 2024Original article

How we use Vale to improve our documentation editing process | Datadog (opens in new tab)

To manage a high volume of technical content across dozens of products, Datadog’s documentation team has automated its editorial process using the open-source linting tool Vale. By integrating these checks directly into their CI/CD pipeline via GitHub Actions, the team ensures prose consistency and clarity while significantly reducing the manual burden on technical writers. This "shift-left" approach empowers both internal and external contributors to identify and fix style issues independently before a formal human review begins. ### Scaling Documentation Workflows * The Datadog documentation team operates at a 200:1 developer-to-writer ratio, managing over 1,400 contributors and 35 distinct products. * In 2023 alone, the team merged over 20,000 pull requests covering 650 integrations, 400 security rules, and 65 API endpoints. * On-call writers review an average of 40 pull requests per day, necessitating automation to handle triaging and style enforcement efficiently. ### Automated Prose Review with Vale * Vale is implemented as a command-line tool and a GitHub Action that scans Markdown and HTML files for style violations. * When a contributor opens a pull request, the linter provides automated comments in the "Files Changed" tab, flagging long sentences, wordy phrasing, or legacy formatting habits. * This automation reduces the "mental toll" on writers by filtering out repetitive errors before they reach the human review stage. ### Codifying Style Guides into Rules * The team transitioned from static editorial guidelines stored in Confluence and wikis to a codified repository called `datadog-vale`. * Style rules are defined using Vale’s YAML specification, allowing the team to update global standards in a single location that is immediately active in the CI pipeline. * Custom regular expressions are used to exclude specific content from validation, such as Hugo shortcodes or technical snippets that do not follow standard prose rules. ### Implementation of Specific Linting Rules * **Jargon and Filler Words:** A `words.yml` file flags "cruft" such as "easily" or "simply" to maintain a professional, objective tone. * **Oxford Comma Enforcement:** The `oxfordcomma.yml` rule uses regex to identify lists missing a serial comma and provides a suggestion to the author. * **Latin Abbreviations:** The `abbreviations.yml` rule identifies terms like "e.g." or "i.e." and suggests plain English alternatives like "for example" or "that is." * **Timelessness:** Rules flag words like "currently" or "now" to ensure documentation remains relevant without frequent updates. By open-sourcing their Vale configurations, Datadog provides a framework for other organizations to automate their style guides and foster a more efficient, collaborative documentation culture. Teams looking to improve prose quality should consider adopting a similar "docs-as-code" approach to shift editorial effort toward the beginning of the contribution lifecycle.

Json ConfigurationDatadogCI/CDGitHub Actions+4