@flowspine/extractor

Static extractor for Flowspine process definitions.

This package reads canonical Flowspine DSL from TypeScript source files and produces a machine-readable process catalog.

Use it when you need to:

• analyze existing process files
• build a process catalog in code
• inspect topology without executing business logic
• build custom tooling on top of Flowspine DSL

Do not use this package for:

• executing steps
• defining process logic
• validating/exporting through standard repository workflows when CLI already solves the task

For standard build/validate/export workflows, prefer @flowspine/cli.

Installation

pnpm add @flowspine/extractor@beta

What This Package Does

The extractor parses Flowspine process files and returns:

• extracted processId
• source file path
• process graph
• diagnostics when extraction is partial or non-canonical

This package is intentionally static.

It does not execute process code and it does not interpret arbitrary TypeScript semantics.

It works best when process files follow canonical Flowspine patterns.

Mental Model

Use @flowspine/extractor when code needs to be treated as data.

Examples:

• “scan all process files in this repo”
• “generate a catalog for a custom viewer”
• “build analysis/reporting around Flowspine DSL”
• “inspect graph structure programmatically”

If the task is instead:

• define flow semantics → use @flowspine/core
• build/validate/export via normal dev workflow → use @flowspine/cli

Main API

import { extractProcessesFromPaths } from "@flowspine/extractor";

Example

import { extractProcessesFromPaths } from "@flowspine/extractor";

const result = extractProcessesFromPaths(["processes/**/*.ts"]);

console.log(result.generatedAt);
console.log(result.processes.length);

for (const process of result.processes) {
  console.log(process.processId, process.sourceFile);

  if (process.diagnostics.length > 0) {
    console.log("diagnostics:", process.diagnostics);
  }
}

Output Shape

Each extracted process includes:

• processId
• sourceFile
• graph
• diagnostics

The result also includes:

• generatedAt
• processes[]

This makes the package useful as a low-level building block for custom automation and repository tooling.

Canonical Patterns It Supports Best

The extractor is designed for canonical Flowspine DSL patterns such as:

import { defineProcess } from "@flowspine/core";

export default defineProcess("order-fulfillment", ({ step, branch, event, action, start, end, link, when }) => {
  const validateOrder = step("ValidateOrder");
  const paymentRequired = branch("PaymentRequired");
  const orderConfirmed = event("OrderConfirmed");

  start(validateOrder);
  link(validateOrder, paymentRequired);
  link(when(paymentRequired, "approved"), orderConfirmed);
  end(orderConfirmed);
});

Supported extraction patterns include:

• defineProcess("id", ({ ... }) => { ... })
• node declarations assigned to variables
• step(...), branch(...), event(...), action(...)
• link(from, to, condition?)
• link(when(branchNode, "condition"), target)
• metadata passed as object literals with supported literal/object/array values

Extraction Limitations

This package does not guarantee full extraction for dynamic or non-canonical code.

Extraction may fail partially or produce diagnostics if you use patterns such as:

• computed process IDs
• computed node IDs
• wrapped or indirect DSL calls
• dynamic metadata values
• non-literal branch conditions
• code structures that hide Flowspine calls from static analysis

In those cases, treat diagnostics as a signal that the source code is harder to analyze statically.

Diagnostics

Diagnostics are warnings produced during extraction when the file is valid enough to inspect partially, but not canonical enough for clean extraction.

Examples of issues that may produce diagnostics:

• metadata is not an object literal
• metadata contains unsupported values
• DSL structure is too indirect for reliable parsing

If you need strict operational validation of a whole repository, run the output through @flowspine/cli.

Typical Use Cases

1. Custom catalog generation

import { extractProcessesFromPaths } from "@flowspine/extractor";

const catalog = extractProcessesFromPaths([
  "processes/**/*.ts",
  "modules/**/processes/**/*.ts"
]);

2. Build your own reporting/tooling

import { extractProcessesFromPaths } from "@flowspine/extractor";

const result = extractProcessesFromPaths(["processes/**/*.ts"]);

const ids = result.processes.map((p) => p.processId);
console.log(ids);

3. Debug extractor compatibility

If a process file is not being extracted as expected, this package helps surface diagnostics before you move up to CLI-level workflows.

When To Prefer CLI Instead

Prefer @flowspine/cli when you need:

• catalog file generation
• repository validation
• graph export
• watch mode
• standard team/CI workflow

The extractor is the lower-level programmatic layer.
The CLI is the operational layer built on top of it.

Related Packages

• @flowspine/core
• @flowspine/cli

License

Apache 2.0

Copyright

Copyright (c) 2026 Flowspine contributors.