Static Analysis

TL;DR

Use awaitly-analyze to extract workflow structure from TypeScript, then render Mermaid/JSON/HTML artifacts for docs, review, and CI checks without running workflows.

When To Use

• You want architecture diagrams from source code, not runtime traces.
• You need deterministic workflow docs in CI.
• You want workflow diffs in PR review.
• You need rule-style diagnostics with stable slug codes.

Static Analysis Pipeline

1

Analyze Source

Parse workflow file and extract IR tree, stats, and references.

2

Render Artifact

Generate Mermaid, JSON, markdown report, or interactive HTML.

3

Apply In Workflow

Use output in docs, PRs, CI gates, and architecture reviews.

Fast start

# Mermaid markdown (default)
npx awaitly-analyze ./src/workflows/checkout.ts

# JSON
npx awaitly-analyze ./src/workflows/checkout.ts --format=json

# Interactive HTML artifact
npx awaitly-analyze ./src/workflows/checkout.ts --html

# Workflow diff
npx awaitly-analyze --diff v1.ts v2.ts

# Strict diagnostics
npx awaitly-analyze ./src/workflows/checkout.ts --doctor

What the analyzer reads

• Step IDs from step('id', fn, opts) as canonical names.
• Workflow and step docs from description and markdown.
• JSDoc descriptions as jsdocDescription fallback.
• Optional step metadata: intent, domain, owner, tags, stateChanges, emits, calls, errorMeta.

CLI reference

Core flags

Flag	Default	Description
--format=<fmt>	mermaid	mermaid, json, markdown
--direction=<dir>	TB	TB, TD, LR, BT, RL
--railway	off	Linear happy-path + ok/err branching
--keys	off	Show step cache keys
--errors / --no-errors	on	Show/hide error nodes
--html	off	Generate interactive HTML artifact
--html-output=<path>	auto	Write HTML to custom path

Output control

Flag	Default	Description
--types / --no-types	on	Generate .types.ts
--test / --no-test	off	Generate test stubs
--test-runner=<runner>	vitest	vitest, jest, mocha
-o, --output-adjacent	off	Write output next to source
--suffix=<value>	workflow	Adjacent output file suffix
--no-stdout	off	Suppress stdout output
--dsl-output=<value>	off	Write DSL output
--write-dsl	off	Same as --dsl-output=.awaitly
--watch	off	Re-analyze on source changes

Interactive HTML artifact

# Writes <basename>.html next to workflow source
npx awaitly-analyze ./src/workflows/checkout.ts --html

# Custom path
npx awaitly-analyze ./src/workflows/checkout.ts --html --html-output=./docs/checkout-diagram.html

The HTML output includes:

• Mermaid rendered client-side.
• Click-to-inspect node details.
• Built-in theme picker with persistence.
• Self-contained payload for easy sharing.

Programmatic API

import {
  analyze,
  renderStaticMermaid,
  renderStaticJSON,
  extractNodeMetadata,
  generateInteractiveHTML,
} from 'awaitly-analyze';

const ir = analyze('./src/workflows/checkout.ts').single();

const mermaid = renderStaticMermaid(ir, { direction: 'TB', showKeys: false });
const json = renderStaticJSON(ir, { pretty: true });

const metadata = extractNodeMetadata(ir);
const html = generateInteractiveHTML(mermaid, metadata, {
  title: 'Checkout Workflow',
  direction: 'TB',
});

Fluent selection helpers

Method	Returns	Throws	Best for
.single()	Single IR	If 0 or >1 workflows	Single-workflow file
.singleOrNull()	IR or null	Never	Optional single workflow
.all()	IR array	Never	Multi-workflow iteration
.named(name)	Single IR	If not found	Named workflow selection
.first()	Single IR	If empty	First workflow only
.firstOrNull()	IR or null	Never	Safe first workflow

Diff workflows

# Local files
npx awaitly-analyze --diff before.ts after.ts

# HEAD vs working copy
npx awaitly-analyze --diff src/workflows/checkout.ts

# Git ref vs local
npx awaitly-analyze --diff main:src/workflows/checkout.ts src/workflows/checkout.ts

# GitHub PR
npx awaitly-analyze --diff gh:#123

import {
  analyze,
  diffWorkflows,
  renderDiffMarkdown,
  renderDiffJSON,
  renderDiffMermaid,
} from 'awaitly-analyze';

const before = analyze('./v1.ts').single();
const after = analyze('./v2.ts').single();

const diff = diffWorkflows(before, after, {
  detectRenames: true,
  regressionMode: false,
});

const md = renderDiffMarkdown(diff, { showUnchanged: true });
const json = renderDiffJSON(diff);
const mermaid = renderDiffMermaid(after, diff, { showRemovedSteps: true, direction: 'TB' });

Diff options

Option	Default	Description
detectRenames	true	Match same callee+position as rename
regressionMode	false	Mark removals as regressions

--doctor diagnostics

Use strict slug-keyed diagnostics aligned with runtime and ESLint rule naming.

awaitly-analyze ./src/workflows/checkout.ts --doctor
awaitly-analyze ./src/workflows/checkout.ts --doctor --format=json

Sample output:

✗ [step-require-id]:12:4
  Step "<missing>" uses legacy signature without explicit ID
  Docs: https://jagreehal.github.io/awaitly/rules/#step-require-id
  Fix: Use step('id', fn, opts) instead of step(fn, opts)

Analyzer output model

interface StaticWorkflowIR {
  root: StaticWorkflowNode;
  metadata: StaticAnalysisMetadata;
  references: Map<string, StaticWorkflowIR>;
}

interface AnalysisStats {
  totalSteps: number;
  conditionalCount: number;
  parallelCount: number;
  raceCount: number;
  loopCount: number;
  workflowRefCount: number;
  unknownCount: number;
}

Node categories:

• StaticStepNode
• StaticSequenceNode
• StaticParallelNode
• StaticRaceNode
• StaticConditionalNode
• StaticLoopNode
• StaticWorkflowRefNode
• StaticUnknownNode

Feature detection coverage

Feature	Detection
Steps	step(), step.retry(), step.withTimeout()
Conditionals	if/else, when*, unless*
Loops	for, while, for-of, for-in
Parallel	step.all(), allAsync(), allSettledAsync()
Race	step.race(), anyAsync()
Workflow refs	Child workflow run calls

Which Output Should You Use?

Choice	Best for	Tradeoff
--format=mermaid	Readable architecture diagrams in docs and PRs.	Less detail than full JSON payload.
--format=json	CI, automation, and custom tooling.	Harder for humans to skim quickly.
--html	Shareable deep review with click-to-inspect details.	Heavier artifact than markdown output.
--diff	PR-level workflow change review.	Requires clean baseline/version selection.
--doctor	Strict diagnostics and policy enforcement.	Can surface warnings that require migration work.

Limitations

• Dynamic step IDs can appear as <dynamic>.
• External workflow references are only resolved when analyzable in context.

Next

• Documenting Workflows →
• Visualization →
• Rules Index →