awaitly-analyze 0.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jag Reehal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,517 @@
+# awaitly-analyze
+
+Static workflow analysis for [awaitly](https://github.com/jagreehal/awaitly). Analyze workflow source code to extract structure, calculate complexity metrics, and generate visualizations.
+
+## CLI Usage
+
+```bash
+# Basic usage - output to stdout
+awaitly-analyze ./src/workflows/checkout.ts
+
+# JSON format
+awaitly-analyze ./src/workflows/checkout.ts --format=json
+
+# Show step keys and change diagram direction
+awaitly-analyze ./src/workflows/checkout.ts --keys --direction=LR
+
+# Write output file adjacent to source (creates checkout.workflow.md)
+awaitly-analyze ./src/workflows/checkout.ts --output-adjacent
+
+# Custom suffix (creates checkout.diagram.md)
+awaitly-analyze ./src/workflows/checkout.ts -o --suffix=diagram
+
+# JSON format with adjacent output (creates checkout.analysis.json)
+awaitly-analyze ./src/workflows/checkout.ts -o --suffix=analysis --format=json
+
+# Write to file only, suppress stdout
+awaitly-analyze ./src/workflows/checkout.ts -o --no-stdout
+
+# Generate interactive HTML with click-to-inspect
+awaitly-analyze ./src/workflows/checkout.ts --html
+
+# Custom HTML output path
+awaitly-analyze ./src/workflows/checkout.ts --html --html-output=./docs/checkout.html
+```
+
+### CLI Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--format=<format>` | `mermaid` | Output format: `mermaid` or `json` |
+| `--html` | - | Generate interactive HTML file (Mermaid CDN + click-to-inspect) |
+| `--html-output=<path>` | `<basename>.html` | Output path for the HTML file |
+| `--keys` | - | Show step cache keys in diagram |
+| `--direction=<dir>` | `TB` | Diagram direction: `TB`, `LR`, `BT`, `RL` |
+| `--output-adjacent`, `-o` | - | Write output file next to source file |
+| `--suffix=<value>` | `workflow` | Configurable suffix for output file |
+| `--no-stdout` | - | Suppress stdout when writing to file (requires `-o`) |
+| `--dsl-output=<value>` | `off` | Write DSL: `off`, `.awaitly`, or custom path (for visualization) |
+| `--write-dsl` | - | Shorthand for `--dsl-output=.awaitly` |
+| `--help`, `-h` | - | Show help message |
+
+### Output File Naming
+
+When using `--output-adjacent`:
+- Mermaid format: `{basename}.{suffix}.md`
+- JSON format: `{basename}.{suffix}.json`
+
+Example: `checkout.ts` with `--suffix=workflow` produces `checkout.workflow.md`
+
+## Features
+
+- **Static Analysis** - Extract workflow structure from TypeScript source without execution
+- **Path Generation** - Enumerate all possible execution paths through a workflow
+- **Complexity Metrics** - Calculate cyclomatic complexity, cognitive complexity, and more
+- **Mermaid Diagrams** - Generate flowchart visualizations
+- **Test Matrix** - Generate test coverage matrices for workflow paths
+- **Cross-Workflow Composition** - Analyze dependencies between workflows
+
+## Installation
+
+```bash
+npm install awaitly-analyze ts-morph
+# or
+pnpm add awaitly-analyze ts-morph
+```
+
+`ts-morph` is a required peer dependency.
+
+## Quick Start
+
+```typescript
+import {
+  analyze,
+  generatePaths,
+  calculateComplexity,
+  renderStaticMermaid,
+} from 'awaitly-analyze';
+
+// Analyze a workflow file
+const ir = analyze('./src/workflows/checkout.ts').single();
+
+// Generate all possible paths
+const paths = generatePaths(ir);
+console.log(`Found ${paths.length} unique execution paths`);
+
+// Calculate complexity metrics
+const metrics = calculateComplexity(ir);
+console.log(`Cyclomatic complexity: ${metrics.cyclomaticComplexity}`);
+
+// Generate Mermaid diagram
+const mermaid = renderStaticMermaid(ir);
+console.log(mermaid);
+```
+
+## API Reference
+
+### Analyzing Workflows
+
+#### `analyze(filePath, options?)`
+
+Returns a fluent interface for analyzing workflows in a file.
+
+```typescript
+import { analyze } from 'awaitly-analyze';
+
+// Single workflow file - get the workflow directly
+const ir = analyze('./checkout.ts').single();
+
+// Multiple workflows - get all as array
+const workflows = analyze('./workflows.ts').all();
+
+// Get specific workflow by name
+const checkout = analyze('./workflows.ts').named('checkoutWorkflow');
+
+// Safe access (returns null instead of throwing)
+const ir = analyze('./checkout.ts').singleOrNull();
+const first = analyze('./workflows.ts').firstOrNull();
+```
+
+#### `analyze.source(code, options?)`
+
+Analyze workflow source code from a string.
+
+```typescript
+const ir = analyze.source(`
+  const workflow = createWorkflow({
+    fetchUser: async (id: string) => ({ id, name: 'Alice' }),
+  });
+
+  async function run(id: string) {
+    return await workflow(async (step, deps) => {
+      const user = await step('fetchUser', () => deps.fetchUser(id), { key: 'user' });
+      return user;
+    });
+  }
+`).single();
+```
+
+### Path Generation
+
+#### `generatePaths(ir, options?)`
+
+Generate all unique execution paths through a workflow.
+
+```typescript
+import { generatePaths, calculatePathStatistics } from 'awaitly-analyze';
+
+const paths = generatePaths(ir, { maxPaths: 100 });
+
+// Get statistics
+const stats = calculatePathStatistics(paths);
+console.log(`Total paths: ${stats.totalPaths}`);
+console.log(`Shortest path: ${stats.shortestPathLength} steps`);
+console.log(`Longest path: ${stats.longestPathLength} steps`);
+```
+
+#### `generatePathsWithMetadata(ir, options?)`
+
+Generate paths with additional metadata about limit hits.
+
+```typescript
+import { generatePathsWithMetadata } from 'awaitly-analyze';
+
+const { paths, limitHit } = generatePathsWithMetadata(ir, { maxPaths: 50 });
+
+if (limitHit) {
+  console.log('Warning: Path limit reached, not all paths generated');
+}
+```
+
+### Complexity Metrics
+
+#### `calculateComplexity(ir)`
+
+Calculate complexity metrics for a workflow.
+
+```typescript
+import { calculateComplexity } from 'awaitly-analyze';
+
+const metrics = calculateComplexity(ir);
+
+console.log(`Cyclomatic complexity: ${metrics.cyclomaticComplexity}`);
+console.log(`Cognitive complexity: ${metrics.cognitiveComplexity}`);
+console.log(`Max nesting depth: ${metrics.maxDepth}`);
+console.log(`Max parallel breadth: ${metrics.maxParallelBreadth}`);
+console.log(`Decision points: ${metrics.decisionPoints}`);
+console.log(`Path count: ${metrics.pathCount}`);
+```
+
+#### `assessComplexity(metrics, thresholds?)`
+
+Get a complexity assessment with warnings.
+
+```typescript
+import {
+  analyze,
+  calculateComplexity,
+  assessComplexity,
+  formatComplexitySummary
+} from 'awaitly-analyze';
+
+const ir = analyze('./checkout.ts').single();
+const metrics = calculateComplexity(ir);
+const assessment = assessComplexity(metrics);
+console.log(formatComplexitySummary(metrics, assessment));
+```
+
+### Mermaid Diagrams
+
+#### `renderStaticMermaid(ir, options?)`
+
+Generate a Mermaid flowchart diagram.
+
+```typescript
+import { renderStaticMermaid } from 'awaitly-analyze';
+
+const mermaid = renderStaticMermaid(ir, {
+  direction: 'TB',  // 'TB' | 'LR' | 'BT' | 'RL'
+  includeKeys: true,
+  includeDescriptions: true,
+});
+
+// Use in markdown:
+// ```mermaid
+// ${mermaid}
+// ```
+```
+
+#### `renderPathsMermaid(ir, paths, options?)`
+
+Generate a diagram highlighting specific paths.
+
+```typescript
+import { renderPathsMermaid, generatePaths } from 'awaitly-analyze';
+
+const paths = generatePaths(ir);
+const diagram = renderPathsMermaid(ir, paths.slice(0, 3));
+```
+
+### Test Matrix
+
+#### `generateTestMatrix(paths)`
+
+Generate a test coverage matrix from paths.
+
+```typescript
+import { generateTestMatrix, formatTestMatrixMarkdown } from 'awaitly-analyze';
+
+const paths = generatePaths(ir);
+const matrix = generateTestMatrix(paths);
+
+// Format as markdown table
+console.log(formatTestMatrixMarkdown(matrix));
+
+// Or as code
+import { formatTestMatrixAsCode } from 'awaitly-analyze';
+console.log(formatTestMatrixAsCode(matrix));
+```
+
+### Cross-Workflow Composition
+
+#### `analyzeWorkflowGraph(files, options?)`
+
+Analyze dependencies between workflows across multiple files.
+
+```typescript
+import {
+  analyzeWorkflowGraph,
+  getTopologicalOrder,
+  renderGraphMermaid,
+} from 'awaitly-analyze';
+
+const graph = analyzeWorkflowGraph([
+  './src/workflows/checkout.ts',
+  './src/workflows/payment.ts',
+  './src/workflows/shipping.ts',
+]);
+
+// Get execution order (workflows with no dependencies first)
+const order = getTopologicalOrder(graph);
+console.log('Execution order:', order.map(n => n.name).join(' -> '));
+
+// Visualize the dependency graph
+const diagram = renderGraphMermaid(graph);
+```
+
+### Interactive HTML
+
+Generate a self-contained HTML file with an interactive Mermaid diagram and a click-to-inspect panel. The output includes 6 color themes, system preference auto-detection, and localStorage persistence.
+
+#### `extractNodeMetadata(ir)`
+
+Walk the IR tree and produce a `WorkflowMetadata` object with per-node details (step IDs, callees, retry/timeout config, types, source locations) keyed by Mermaid node ID.
+
+```typescript
+import { analyze, extractNodeMetadata } from 'awaitly-analyze';
+import type { WorkflowMetadata } from 'awaitly-analyze';
+
+const ir = analyze('./checkout.ts').single();
+const metadata: WorkflowMetadata = extractNodeMetadata(ir);
+```
+
+#### `generateInteractiveHTML(mermaidText, metadata, options?)`
+
+Combine Mermaid text from `renderStaticMermaid()` with metadata from `extractNodeMetadata()` into a complete HTML string.
+
+```typescript
+import {
+  analyze,
+  renderStaticMermaid,
+  extractNodeMetadata,
+  generateInteractiveHTML,
+} from 'awaitly-analyze';
+import type { InteractiveHTMLOptions } from 'awaitly-analyze';
+
+const ir = analyze('./checkout.ts').single();
+const mermaid = renderStaticMermaid(ir);
+const metadata = extractNodeMetadata(ir);
+const html = generateInteractiveHTML(mermaid, metadata, {
+  theme: 'midnight',          // 'midnight' | 'ocean' | 'ember' | 'forest' | 'daylight' | 'paper'
+  title: 'Checkout Workflow', // defaults to workflow name
+  direction: 'TB',            // diagram direction
+});
+
+import { writeFileSync } from 'node:fs';
+writeFileSync('checkout.html', html);
+```
+
+**`InteractiveHTMLOptions`:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `title` | `string` | workflow name | Page title |
+| `theme` | `string` | auto-detect | Initial color theme |
+| `mermaidCdnUrl` | `string` | latest v11 | Mermaid CDN URL |
+| `direction` | `"TB" \| "LR" \| "BT" \| "RL"` | `"TB"` | Diagram direction |
+
+### Workflow Diagram DSL
+
+#### `renderWorkflowDSL(ir)`
+
+Produce a state-machine-like DSL for xstate-style visualization (states and transitions with event labels). Types are defined in `awaitly/workflow`; the analyzer emits DSL that conforms to them.
+
+```typescript
+import { analyze, renderWorkflowDSL, writeDSLToAwaitlyDir } from 'awaitly-analyze';
+import type { WorkflowDiagramDSL } from 'awaitly/workflow';
+
+const ir = analyze('./checkout.ts').single();
+const dsl: WorkflowDiagramDSL = renderWorkflowDSL(ir);
+
+// Optional: write to .awaitly/dsl/ (default) or a custom folder
+await writeDSLToAwaitlyDir(dsl, { rootDir: process.cwd() });
+// Custom folder: await writeDSLToAwaitlyDir(dsl, { rootDir: process.cwd(), outputDir: 'dist/dsl' });
+```
+
+**Snapshot alignment:** When a workflow is running, `WorkflowSnapshot.execution.currentStepId` holds the step key. DSL step state ids use the same step key so a visualizer can highlight the current node. See `awaitly/workflow` diagram-dsl types for details.
+
+### JSON Output
+
+#### `renderStaticJSON(ir, options?)`
+
+Serialize workflow IR to JSON.
+
+```typescript
+import { renderStaticJSON } from 'awaitly-analyze';
+
+const json = renderStaticJSON(ir, { pretty: true });
+fs.writeFileSync('workflow.json', json);
+```
+
+## Detected Patterns
+
+The analyzer detects the following awaitly patterns:
+
+- `createWorkflow()` - Standard workflow creation
+- `run()` - Inline workflow execution
+- `createSagaWorkflow()` - Saga workflow creation
+- `runSaga()` - Inline saga execution
+
+Within workflows, it detects:
+
+- `step('id', fn, opts?)` - Single steps (string ID required) with retry/timeout options
+- `step.parallel()` / `allAsync()` / `allSettledAsync()` - Parallel execution
+- `step.race()` / `anyAsync()` - Race execution
+- `step.sleep(id, duration, opts?)` - Sleep steps (ID required as first argument)
+- `step.retry(id, operation, opts)` - Retry wrappers (ID required as first argument)
+- `step.withTimeout(id, operation, opts)` - Timeout wrappers (ID required as first argument)
+- `step.try(id, operation, opts)` - Try/catch steps (ID required as first argument)
+- `step.fromResult(id, operation, opts)` - FromResult steps (ID required as first argument)
+- `step.getWritable()` / `step.getReadable()` / `step.streamForEach()` - Streaming
+- `when()` / `unless()` / `whenOr()` / `unlessOr()` - Conditional helpers
+- `if/else`, `switch` - Control flow
+- `for`, `while`, `forEach`, `map` - Loops
+- Saga steps with compensation (`saga.step()`, `saga.tryStep()`)
+
+## Import Styles
+
+The analyzer supports various import styles:
+
+```typescript
+// Named imports
+import { createWorkflow, run } from 'awaitly';
+
+// Aliased imports
+import { createWorkflow as cw } from 'awaitly';
+
+// Namespace imports
+import * as Awaitly from 'awaitly';
+Awaitly.createWorkflow({...});
+
+// Default imports
+import Awaitly from 'awaitly';
+Awaitly.run(async (step) => {...});
+```
+
+## Types
+
+Key types exported from the package:
+
+```typescript
+import type {
+  // IR nodes
+  StaticWorkflowIR,
+  StaticFlowNode,
+  StaticStepNode,
+  StaticParallelNode,
+  StaticConditionalNode,
+
+  // Paths
+  WorkflowPath,
+  PathStatistics,
+
+  // Complexity
+  ComplexityMetrics,
+  ComplexityAssessment,
+
+  // Test matrix
+  TestMatrix,
+  TestPath,
+
+  // Graph
+  WorkflowGraph,
+  WorkflowGraphNode,
+
+  // Interactive HTML
+  NodeMetadata,
+  WorkflowMetadata,
+  InteractiveHTMLOptions,
+} from 'awaitly-analyze';
+```
+
+### API types reference
+
+Main static-analysis node types and when fields are populated:
+
+- **StaticWorkflowNode** (root): `workflowName`, `source`, `dependencies`, `children`, `description`, `markdown`, `jsdocDescription?`, `errorTypes`.  
+  `description` and `markdown` are set only for `createWorkflow` / `createSagaWorkflow` (from options or deps). They are undefined for `run()` / `runSaga()` (no options object). `jsdocDescription` is extracted from JSDoc above the workflow variable when present.
+
+- **StaticStepNode**: `stepId`, `callee`, `name`, `key`, `description`, `markdown`, `jsdocDescription?`, `retry`, `timeout`.  
+  `stepId` is the required first argument for all step types: `step('id', fn, opts)`, `step.sleep('id', duration, opts?)`, `step.retry('id', operation, opts)`, `step.withTimeout('id', operation, opts)`, `step.try('id', operation, opts)`, `step.fromResult('id', operation, opts)`. Legacy `step(fn, opts)` is still parsed but yields `stepId: "<missing>"` and a warning. `description` and `markdown` come from step options; `jsdocDescription` is extracted from JSDoc above the step statement when present.
+
+- **StaticSagaStepNode**: `callee`, `name`, `description`, `markdown`, `jsdocDescription?`, `hasCompensation`, `compensationCallee`, `isTryStep`.  
+  `description` and `markdown` come from saga step options (e.g. `saga.step(fn, { description, markdown })`). `jsdocDescription` is extracted from JSDoc above the saga step statement when present.
+
+- **DependencyInfo**: `name`, `typeSignature?`, `errorTypes`.  
+  `typeSignature` is the TypeScript type of the dependency (e.g. the function type), when the type checker is available; it may be undefined. `errorTypes` is not yet inferred from types and is typically empty.
+
+### JSDoc
+
+The analyzer extracts JSDoc comments from workflow declarations (`createWorkflow` / `createSagaWorkflow` variable statements) and from step call sites (the statement containing `await step(...)`, `step.sleep(...)`, `saga.step(...)`, etc.). Extracted text is exposed as **`jsdocDescription`** on the root (`StaticWorkflowNode`) and on step nodes (`StaticStepNode`, `StaticSagaStepNode`). Only the main description (text before the first `@tag`) is extracted; `@param` / `@returns` are not parsed into separate fields. Option-based `description` and `markdown` remain the canonical documentation fields and take precedence for display; JSDoc is additive so consumers can use `description ?? jsdocDescription` for fallback.
+
+### JSON output shape
+
+The output of `renderStaticJSON(ir)` has this structure. Agents and doc generators can use it to parse or validate the JSON.
+
+- **Top level**: `{ root, metadata?, references? }`
+  - `root`: StaticWorkflowNode (see below)
+  - `metadata`: `{ analyzedAt, filePath, tsVersion?, warnings?, stats? }`
+  - `references`: object mapping workflow name to `{ root, metadata? }` (when inlined)
+
+- **StaticWorkflowNode** (`root`): `type: "workflow"`, `id`, `workflowName`, `source?`, `dependencies[]`, `errorTypes[]`, `children[]`, `description?`, `markdown?`, `jsdocDescription?`, `name?`, `key?`, `location?`
+
+- **DependencyInfo** (each entry in `dependencies`): `name`, `typeSignature?`, `errorTypes[]`
+
+- **Flow nodes** (`children` and nested): discriminated by `type`:
+  - `"step"`: `id`, `stepId`, `name?`, `key?`, `callee?`, `description?`, `markdown?`, `jsdocDescription?`, `retry?`, `timeout?`, `location?`
+  - `"saga-step"`: `id`, `name?`, `callee?`, `description?`, `markdown?`, `jsdocDescription?`, `hasCompensation`, `compensationCallee?`, `isTryStep?`, `location?`
+  - `"sequence"`: `id`, `children[]`
+  - `"parallel"`: `id`, `children[]`, `mode` ("all" | "allSettled"), `callee?`
+  - `"race"`: `id`, `children[]`, `callee?`
+  - `"conditional"`: `id`, `condition`, `consequent[]`, `alternate?`, `helper?`, `defaultValue?`
+  - `"switch"`: `id`, `expression`, `cases[]` (each: `value?`, `isDefault`, `body[]`)
+  - `"loop"`: `id`, `loopType`, `body[]`, `iterSource?`, `boundKnown`, `boundCount?`
+  - `"stream"`: `id`, `streamType`, `namespace?`, `options?`, `callee?`
+  - `"workflow-ref"`: `id`, `workflowName`, `resolved`, `resolvedPath?`, `inlinedIR?`
+  - `"unknown"`: `id`, `reason`, `sourceCode?`
+
+A JSON Schema for this structure is available at `schema/static-workflow-ir.schema.json` in this package.
+
+## Requirements
+
+- Node.js >= 22
+- TypeScript project with `ts-morph` >= 27.0.2
+
+## License
+
+MIT